Authentication¶

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

Overview¶

For using any Billtrust API, you will first need to be authenticated as a valid user. There are two ways to authenticate - with an API Key or with an authentication token.

An API Key is the preferred method for authenticating in order to use a Billtrust API. 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 to the API Key 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. Auth tokens will expire after a certain amount of time and will need to be refreshed or regenerated.

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 API Key generated above into all API calls in a header named X-Billtrust-Api-Key.

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¶

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

Authentication¶

Overview¶

API Key¶

Generate an API Key¶

Using the API Key¶

Removing an API Key¶

Authentication Token¶

Login¶

Using Authentication Token¶

Refreshing a Token¶

Logout¶