Skip to main content

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 integration.

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 - private keys cannot be stored on a front end only application

Initial API Key Setup#

To obtain the client keys you will need to perform the following steps:

  1. Navigate to the Integrations section in the dashboard, or simply click the “Add Integration” option

  2. Choose the "Management" as an integration type

  3. Choose the "New API Credential" to create a new api private key

  4. Enter a name for your management integration and API credential and press Create

  5. Copy the API Private Key and use it to fill the API_PRIVATE_KEY variable:

    API_PRIVATE_KEY=-----BEGIN EC PRIVATE KEY-----\nTOKEN\n-----END EC PRIVATE KEY-----
info

API_PRIVATE_KEY has to be entered as a single line string with all newlines replaced with \n character.

Create an API Service Token#

The easiest way to generate an API Service Token is to use one of our Server SDKs. If that 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 Authorization: Bearer <token> header before sending requests.

Required Token Payload#

{
  "type": "<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>
}

Required Token Header#

{
  "alg": "ES256",
  "typ": "JWT"
}

Once the token is created, it must be signed with the ES256 algorithm using the API_PRIVATE_KEY.

How to find out which scope is required?#

To see the required scope for each endpoint, please refer to the documentation for the respective flows. Below is a list of some of the endpoints and their respective scopes.

EndpointRequiredScope
POST /register/fido2/initOptionalauth.register
POST /register/passwordOptionalauth.register
POST /authenticate/fido2/initOptionalauth.login
POST /authenticate/passwordOptionalauth.login
POST /codes/{type}/generateYescodes.generate
POST /codes/{type}/authorizeYescodes.authorize
POST /codes/{type}/invalidate-allYescodes.invalidate
GET /credentialsYescredentials.list
POST /credentials/renameYescredentials.rename
POST /credentials/revokeYescredentials.revoke
POST /credentials/fido2/init/codeOptionalcredentials.add
POST /manage/users/retrieveYesusers.retrieve
POST /manage/users/deleteYesusers.delete
DELETE /manage/users/{user_id}Yesusers.delete
PUT /manage/users/{user_id}/activateYesusers.activate
PUT /manage/users/{user_id}/deactivateYesusers.deactivate
POST /txYestx.create
POST /tx/initOptionaltx.create

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.