Connecting and Authenticating to the AMS API

This article walks you through connecting to the AMS public API, logging in, obtaining an authentication token and making your first API request.

The API enables authorised external systems to interact with AMS without using the standard web interface.

You will need:

• An AMS account authorised to access the API.

• The username (email address) and password for that account.

• Access to the account's email if one-time password (OTP) authentication is enabled.

• The relevant permissions for the API actions you intend to perform.

• 401 Unauthenticated = not logged in, invalid token or expired authentication.

• 403 Forbidden = the API user does not have the required permissions.

Setup order

1. Step 1 - Ensure correct API URL

2. Step 2 - Log in to AMS

3. Step 3 - Retrieve your authentication token

4. Step 4 - Authenticate subsequent requests

5. Step 5 - Refresh your token

Step 1 - Identify your API URL

The AMS API uses the base path:

/api

The documented API endpoints use version 2 (/v2).

For example, the user-list endpoint is:

/api/v2/admin/users

• The endpoint paths are case-sensitive and should be copied exactly.

• The API documentation includes AMS-specific and shared administration endpoints.

• Older API documentation is being deprecated. New integrations should use the documented /v2 endpoints.

• The endpoints available to your organisation can depend on your licence and environment.

Step 2 - Log in to AMS

Endpoint: POST /v2/login

Submit your AMS login credentials.

Example request body

{
  "email": "integration@example.org",
  "password": "YOUR_PASSWORD"
}

• If MFA is enabled, the login process requires an email OTP.

• An initial request without the OTP may return 202, indicating that the email has been sent.

• Complete login using the OTP to obtain the authentication token.

• Repeated incorrect passwords may cause the account to be locked.

Step 3 - Retrieve your authentication token

Once authentication is successful, the API returns an access token.

The response also includes a ttl value, which specifies the duration of the token in minutes.

Successful response: 200 OK

Store the token securely. It will be needed for subsequent API requests.

Step 4 - Authenticate subsequent requests

Use the token in the Authorization header.

Example header

Authorization: Bearer YOUR_ACCESS_TOKEN

The token must be valid, and the authenticated account must have the permissions required by the endpoint.

For example:

Endpoint: GET /v2/admin/users

Permission required: read_users

A successful response will return user information accessible to the authenticated account.

Step 5 - Refresh your token

Endpoint: GET /v2/refresh

The endpoint returns a new authentication token.

• The existing token must still be valid.

• Supply the current token in the Authorization header.

• The previous token is invalidated when a new one is issued.

• Use the newly issued token for subsequent requests.