Skip to main content

Authentication

In order to issue calls to our API you must authenticate your requests. 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 kinds of tokens for authentication. These are user tokens and application tokens.

User Tokens​

User tokens are for use with frontend applications. Our embedded payments API provides user management capabilities and allows said 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"
  }
}

As you can see above here we are sending the email and password of the user. We are also sending the name of the application. This field can be omitted in requests from a browser as we will use the origin url to detect your application.

Application Tokens​

Application tokens are for use with your application where rather than authenticating as a user you want 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 you are boarded onto one of our environments you will recieve an application token and application name. It is recommended to store the application token somewhere safe, 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 that the request authorization token is associated with.

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"
    ]
  }
}

Now that you know a thing or to about our API and how to authenticate, you should learn about our API Conventions next.