Skip to content

Authentication

Platform lane only

This page describes Platform API authentication on https://arc-aegis.billtrust.com (login token + self-serve platform API keys).

Ingest, Remittance export, and other External APIs on https://ext.arc-aegis.billtrust.com use a different key (btk_…) issued through the platform Ext API Keys experience — not the create-key calls below.

Start with Connect if you are unsure which lane your product uses.

API Gateway Address: https://arc-aegis.billtrust.com/authentication

Overview

For Platform Billtrust APIs, you must authenticate as a valid platform user. There are two ways: an API key (preferred for integrations) or an authentication token (login).

An API key can be created for any valid user of the platform. The key grants the requestor the same access and permissions as the user it is associated with. API keys expire after 1 year of inactivity.

An authentication token is an alternative for calling most platform routes. The API uses this token to validate tenant access and permissions. Auth tokens expire and must be refreshed or regenerated.

External API products (Ingest, Remittance export) do not use this Authentication API to mint their external API keys. See Connect — External lane.

API Key

Generate an API Key

An authentication token is needed to generate an API Key. Before proceeding, obtain an auth token using the Authentication/login route. This is the only time an auth token will be used. Once an API Key is generated, there is no need to continue using an auth token.

To create an API Key, first create a user with the role needed for accessing the desired APIs. It is recommended that you create a special user for this purpose, and do not reuse a user account that could later be deactivated or have its permissions altered.

Once the user is created, the API Key can be generated with a call to the Authentication API.

Example:

curl -X POST 'https://arc-aegis.billtrust.com/authentication/v1/tenants/{tenantId}/users/profile/api-key' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Auth: <token value>'

If successful, this will return a payload like:

{
    "createDateInMillis":1563459448824,
    "keyId":"(removed)",
    "apiKey":"(removed)",
    "expiresAtInMills":0
}

The value in apiKey is your permanent API Key.

IMPORTANT: There is no way to query the system for your API Key once it has been generated, so make sure to store the API Key and keyID in a secure location.

Using the API Key

Pass the platform API key on Platform API calls in a header named X-Billtrust-Api-Key.

Do not assume this key authorizes External APIs (ext.arc-aegis…). Those require an external key — see Connect.

Example:

curl -X GET 'https://arc-aegis.billtrust.com/user/v1/users/profile' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Removing an API Key

API Keys are permanent unless the user account they are associated with is removed or the API Key itself is deleted. API Keys are deleted after 1 year of inactivity. An API Key can also be deleted with a call to the Authentication API.

curl -X DELETE 'https://arc-aegis.billtrust.com/authentication/v1/tenants/{tenantId}/users/profile/api-key/{keyId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Auth: <token value>'

Authentication Token

Login

It is recommended that you use an API Key to access Billtrust APIs. The instructions below are only needed if you instead wish to authenticate using a username and password. Unless you are generating or removing a key, API Key users can skip this section.

An authentication token is needed in order to call almost all routes in our API. The API uses this token to validate that you have access to the tenant you are trying to affect, and that you have permissions that let you call the API in question. Perform a login to get an authentication token by using the authentication/login route.

Example:

curl -X POST 'https://arc-aegis.billtrust.com/authentication/v1/login' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "email": "william.trust@billtrust.com", "password": "password123"}'

If successful, this will return a payload like:

{
  "status": "LOGIN_SUCCESS",
  "userId": "(removed)",
  "email": "william.trust@billtrust.com",
  "accessToken": "(removed)",
  "expiresIn": 3600,
  "createdDate": "2018-09-13T03:39:48.5816637Z",
  "tenants": [
    {
      "tenantId": "(removed)",
      "tenantName": "Billtrust",
      "isPartner": true,
      "testTenantId": null
    }
  ],
  "defaultTenantId": "(removed)"
}

Using Authentication Token

Store the accessToken from the above login response and pass it in all subsequent API calls in a header named X-Billtrust-Auth.

Example:

curl -X GET 'https://arc-aegis.billtrust.com/user/v1/users/profile' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Auth: <token value>'

Refreshing a Token

Access tokens will expire after a set amount of time (default of 15 minutes) if they are not used. It is recommended that if your process has delays between executing requests that you periodically refresh your token using the Verify Session endpoint.

Example:

curl -X POST 'https://arc-aegis.billtrust.com/authentication/v1/verify-session' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "accessToken": "<token value>"}'

If successful, this will return a payload like:

{
  "verified": true,
  "status": "ACCESSTOKEN_VERIFIED"
}

Logout

Once your process is finished invoking the APIs, it is recommended that you log out your session. This will ensure that your session is closed and that no further requests can be made using the token. If logout is not explicitly called, the token will naturally expire after the expiration time elapses.

Example:

curl -X POST 'https://arc-aegis.billtrust.com/authentication/v1/logout' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "accessToken": "<token value>" }'

Product-specific authentication

Some Billtrust product APIs use a different credential model than the Platform API Key / access token flow above.

  • BT Collections uses per-platform Bearer tokens created under Collections Settings → API Tokens. See Collections Authentication.