API Service Tokens
To call protected LoginID API endpoints, developers need to authenticate with an access token called the API service token. These tokens are JSON Web Tokens (JWTs) which contain specific grant permissions known as scopes. These tokens are signed by the API Credential Private Key
which has been assigned to the application.
This is similar to the credentials you would create with Google to use Google authentication. This allows you to use LoginID services in a secure, authenticated fashion.
Prerequisites
- Existing admin / developer account (i.e. access to the dashboard)
- A backend application - private keys cannot be stored on a front end only application
Initial API Credential Setup
To set up an API credential, you will need to perform the following steps:
Navigate to the
Applications
section in the dashboardChoose the
Add API Credential
option to create a new API credential- This generates a public private key pair. We only store the public key and use it to validate signed requests from you.
Assign the newly created API credential to an existing application
Copy the API Private Key and use it to fill the
API_PRIVATE_KEY
variable:API_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\nTOKEN\n-----END PRIVATE KEY-----
API_PRIVATE_KEY
has to be entered as a single line string with all newlines replaced with the \n
character.
Create an API Service Token
The easiest way to generate an API Service Token is to use one of our Server SDKs. Our SDKs automatically create the appropriate token on your behalf, simplifying the flow. If using a server SDK does not suite your needs, you can continue below to understand how to generate a service token yourself.
An API service token has to be signed by the API Credential Private Key and added to request headers as the Authorization: Bearer <token>
header.
Required Token Payload
{
"scope": "<scope of requested API endpoint call>",
"username": "<end user’s username if included in request body>",
"nonce": "<unique per-request value to prevent repeated requests with the same JWT>",
"iat": "<issue date of the token in epoch seconds>"
}
The username
field is only required if the username
is included in the request payload.
Required Token Header
{
"alg": "ES256",
"typ": "JWT"
}
Once the token is created, it must be signed with the ES256 algorithm using the API_CREDENTIAL_PRIVATE_KEY
.
How to find out which scope is required?
To see the required scope for each endpoint, please refer to the OpenAPI documentation for detail.
Token security and lifetime
The API service token is a short-lived token which expires in 5 minutes. Each token must contain a nonce value which ensures that it is expired once the request is sent. The same token cannot be used to make a new request. A new token must be created when a new request is made.