Skip to main content

Authentication

In order to issue calls to Exact APIs, requests must be authenticated. As mentioned in the introduction, this can be done by adding an Authorization header to your requests with the value of the token.

It is important to note that our API accepts two token types for authentication. These are user tokens and application tokens.

User Tokens

User tokens are for use with frontend applications. Exact's embedded payments APIs provides user management capabilities and allows users to access the API via their credentials. A user's capabilities are determined by their role and permissions.

User tokens are best used for frontend authentication as they expire after 2 hours of inactivity. They should not be used for servers or application backends unless authenticating on a user's behalf. For long living API access, see application tokens below.

User tokens are created by issuing the following request:

{
"method": "post",
"url": "https://api.exactpaysandbox.com/token",
"body": {
"email": "[email protected]",
"password": "A rather secure password",
"application": "harrison-widgets-app"
}
}

This request includes email and user password as well as the application name. This field can be omitted in requests from a browser as the platform will use the origin url to detect your application.

Application Tokens

Application tokens are for use with your application. Rather than authenticating as a user, use Application tokens to authenticate as an application. This is the most common form of authentication as these tokens will not expire, but do require you to specify which permissions you wish to use upfront.

When boarded onto the Exact platform, you will receive an application token and application name. It is recommended to securely store the application token and to create additional application tokens with a narrower set of permissions to better control access to your account.

Application tokens do not expire and can be used by your systems as long as needed, or until someone with the permission to do so deletes the token.

You will also need to provide your application name. The application name provided determines what application settings such as email templates to use for this session.

Application tokens are created by issuing the following request:

{
"method": "post",
"url": "https://api.exactpaysandbox.com/application/{applicationName}/token",
"headers": {
"Authorization": ""
},
"body": {
"label": "My API Token",
"permissions": [
"accounts.read"
]
}
}

The above request creates a new application with the accounts.read permission. The new application token will be associated with the same organization or account as the request authorization token.

In order to create an authentication token under a sub-organization the following request can be used:

{
"method": "post",
"url": "https://api.exactpaysandbox.com/application/{applicationName}/organization/{organizationId}/token",
"headers": {
"Authorization": ""
},
"body": {
"label": "My API Token",
"permissions": [
"accounts.read"
]
}
}

Notice the added organization/{organizationId} part of the path. The same can be done for accounts:

{
"method": "post",
"url": "https://api.exactpaysandbox.com/application/{applicationName}/account/{accountId}/token",
"headers": {
"Authorization": ""
},
"body": {
"label": "My API Token",
"permissions": [
"charges.read"
]
}
}

For additional information on our API Conventions