Authentication

🚧
Master: api-docs.aerahost.com
We're moving our API docs to docs.aera.id. Until the move is done, 3. Access API, 4. Access PSP, 20.2. Authentication and Authorization and 20.4. Request Headers on api-docs.aerahost.com are the master for this page. If this page and api-docs differ, api-docs is right.

Every request to Aera's REST APIs needs:

Your API key in the x-api-key header.
An access token in the Authorization header: Authorization: Bearer <access token>. A few endpoints, such as status checks, need only the API key.

Request headers

Header	When	Example
`x-api-key`	Every request	`x-api-key: <API key>`
`Authorization`	Every request, except when you ask for a token	`Authorization: Bearer <access token>`
`Content-Type`	Requests with a body	`Content-Type: application/vnd.payments.v1+json`
`Accept`	Most requests	`Accept: application/vnd.payments.v1+json`

Content-Type and Accept also say which version of the API you use. Check each API's reference for the exact value. See Versioning and changes.

Which token service to use

Your API	Token service	Get a token
Online payments	Access PSP	`POST /access/v1/oauth2/token` on `psp.aerahost.com`
Reporting API and other services on `api.aerahost.com`	Access API	`POST /access/oauth2/token` on `api.aerahost.com`

Use the test hosts while you build. See Environments.

sequenceDiagram
    participant S as Your system
    participant A as Access PSP or Access API
    participant R as Aera API
    S->>A: Client ID, client secret and API key
    A-->>S: Access token and refresh token
    S->>R: Request with API key and access token
    R-->>S: Response

Get an access token

Send grantType password, your client ID as username and your client secret as password, with your API key in x-api-key.
Aera answers 201 Created with an accessToken, a refreshToken and expiresIn.
Send the access token in the Authorization header of your next requests.

Example token request

{
  "grantType": "password",
  "username": "<client ID>",
  "password": "<client secret>"
}

Example token response

{
  "accessToken": "eyJhbGciOiJSUzI1NiJ9.example",
  "refreshToken": "eyJhbGciOiJSUzI1NiJ9.refresh-example",
  "expiresIn": "600",
  "responseInfo": {
    "responseCode": "0",
    "timeStamp": "2026-03-11T17:46:02.120Z"
  }
}

When the token expires

expiresIn tells you how many seconds the access token is valid. Before it runs out, get a new one: send grantType refresh_token with the refreshToken, or send grantType password again.

To check whether a token is still active, use oauth2/introspect on Access PSP or Access API.