General aspects

Partium offers various authentication options, and this article covers them in detail.

API Keys

The easiest way to set up your integration is by creating an API Key and using this secret for every interaction. When creating an API key, it is associated with the organization where the user holds a developer role. If a user holds a developer role in multiple organizations, the organization is selected during API key creation, and the key is valid only for that organization. To create an API key for a specific organization, you need to log in to that organization first.

The API Key must be sent along as a Bearer token.

---

HTTP

POST https://api.partium.io/1/find/search
Authorization: Bearer <<Your API Key>>

{
...
}

Python

response = requests.post(
  'https://api.partium.io/1/find/search',
  headers={
    'Authorization': 'Bearer <<Your API Key>>',
  },
  ...
)

JavaScript

fetch('https://api.partium.io/1/find/search', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your API Key>>',
  },
  ...
}).then(res => {
  ...
});

Find SDK

Partium.initApiKey('<<Your API Key >>');

note

Replace <<Your API Key>> with your API Key's value.

---

info

Despite being the easiest way, it comes with some implications that one needs to consider:

• Secret can be exposed, leading to data leakage.
• Users share the same access, making it harder to collect valuable usage insights.

See API Key exchange below for an option to prevent secret exposure.

OAuth

Another option for authenticating is using an OAuth Access Token. It provides a secure method of authenticating users with temporary credentials. These credentials can then be sent along with every interaction, as a Bearer token:

---

HTTP

POST https://api.partium.io/1/find/search
Authorization: Bearer <<Your Access Token>>

{
...
}

Python

response = requests.post(
  'https://api.partium.io/1/find/search',
  headers={
    'Authorization': 'Bearer <<Your Access Token>>',
  },
  ...
)

JavaScript

fetch('https://api.partium.io/1/find/search', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token>>',
  },
  ...
}).then(res => {
  ...
});

Find SDK

Partium.initApiKey('<<Your Access Token >>');

note

Replace <<Your Access Token>> with your API Key's value.

---

Obtaining an access token

An Access Token can be obtained by exchanging valid credentials with an Identity Provider.

Before proceeding with the exchange process, the authentication system needs to be configured

Any OIDC Identity Provider can be connected to Partium's authentication system for integrated user management.

Another alternative is to use Partium's Identity Provider, where user management is conducted offline, and user email lists and access roles need to be sent to Partium beforehand.

In either case, talk to your Partium Account Manager to learn more about both options and to quickly get set up.

As soon as the Identity Provider is configured, an Access Token can be retrieved and used as described above.

Authentication API

Partium offers an Authentication API to simplify managing Access Tokens, eliminating the need to connect to external partners or other systems.

Below, the available options for exchanging credentials for access tokens are described.

User:Password exchange

Makes it possible to retrieve an Access Token by providing per-user credentials to the authentication API using the Authorization: Basic header.

---

HTTP

POST https://api.partium.io/auth/
Authorization: Basic base64(<<usename>>:<<password>>)

Python

response = requests.post(
  'https://api.partium.io/1/auth',
  headers={
    'Authorization': f'Basic {base64.b64encode("<<usename>>:<<password>>".encode()).decode())}',
  },
  ...
)

JavaScript

fetch('https://api.partium.io/auth/', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${btoa("<<usename>>:<<password>>")}`,
  },
  ...
}).then(res => {
  ...
});

note

Replace <<username>> and <<password>> accordingly.

---

Pros:

• Users can be uniquely identified
• Secure even for mobile and web applications
• No credentials or secrets need to be stored

Cons:

• Users are managed offline
• Additional credentials are required for the user
• An additional login step is necessary

API Key exchange

Makes it possible to exchange an API secret for an Access Token. It can be utilized to facilitate a rapid integration setup while preventing the direct exposure of the API Key secret in client application code.

---

HTTP

POST https://api.partium.io/auth/
Authorization: Bearer <<Your API Key>>

Python

response = requests.post(
  'https://api.partium.io/1/auth',
  headers={
    'Authorization': 'Bearer <<Your API Key>>',
  },
  ...
)

JavaScript

fetch('https://api.partium.io/auth/', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your API Key>>',
  },
  ...
}).then(res => {
  ...
});

note

Replace <<Your API Key>> with your API Key's value.

---

Pros:

• Minimal setup required
• Secure even for mobile and web applications

Cons:

• Secrets need to be securely stored
• A backend application layer is required
• Users cannot be uniquely identified

Refresh Token exchange

All Access Tokens obtained via the Authentication API are valid for a specific time span, by default set to 600 seconds. Before this time span expires, it is possible to exchange a Refresh Token for a new Access Token with a new expiration.

---

HTTP

POST https://api.partium.io/auth/refresh
Content-Type: application/json

{
  "refresh_token": "<<Your Refresh Token>>"
}

Python

response = requests.post(
  'https://api.partium.io/auth/refresh',
  json={
    'refresh_token': '<<Your Refresh Token>>',
  },
  ...
)

JavaScript

fetch('https://api.partium.io/auth/refresh', {
  method: 'POST',
  body: {
    refresh_token: '<<Your Refresh Token>>',
  },
  ...
}).then(res => {
  ...
});

note

Replace <<Your Refresh Token>> with your refresh token value.

---

Check the Authentication API Reference for more details.