Skip to main content
Version: 2.0.0-beta

Authorization Tokens

To access backend LoginID API endpoints, developers need to authenticate with an access token. These tokens are JSON Web Tokens (JWTs), in other words these are authorization tokens. These tokens are signed by the private key which has been assigned to the tenant.

Services Which Required Authorization Tokens

  • Users API

Prerequisites

  • A tenant with an assigned private key

Setup

Head over to the customer dashboard and create a new tenant. Select any tenant type.

note

All tenants are eligible to utilize backend APIs. The only prerequisite is the assignment of an ES256 private key to the tenant.

In the Advanced Configuration tab, click on Generate Key Pair. This action triggers the creation of an ES256 keypair through the Web Crypto API. Please note that the private key is visible only once and can be copied and securely stored on your end. The public key will be transmitted to LoginID and used for verifying signed authorization tokens with the corresponding private key.

Proceed to configure the remaining tenant settings and finalize the tenant creation.

Importing the ES256 Private Key

The recommended method for importing the private key into your backend is to use a .pem file. However, if you choose to import it as an environment variable, format it as follows:

API_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\nTOKEN\n-----END PRIVATE KEY-----
note

Ensure that API_PRIVATE_KEY is entered as a single-line string with all newlines replaced by the \n character.

When imported into your backend, you'll need to reformat it. Here's an example in Node.js:

const privateKey = process.env.PRIVATE_KEY.replace(/\\n/g, '\n'),

This ensures proper handling of the private key in your backend environment.

Creating an Authentication Token

To generate an authorization token, sign it with the private key acquired from the tenant and include it in the request headers as Authorization: Bearer <token>.

You can use any cryptography library that supports signing with ES256 private keys for token signing.

Required Token Payload

The following claims are necessary for authentication by LoginID:

{
"iss": "loginid.io",
"aud": "<hostname of your tenant base URL>",
"exp": "<expiry date of the token in epoch seconds>"
}
note
  • The iss claim is always fixed to loginid.io
  • For the aud claim, use the hostname of your tenant base URL. For instance, if your tenant base URL is https://qrtg4rxycm0mqet-uicunq.gen2.playground.loginid.io, then the hostname would be qrtg4rxycm0mqet-uicunq.gen2.playground.loginid.io.

Required Token Header

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

Once the token is created, it must be signed with the ES256 algorithm using the provided private key.

Token security and lifetime

While any expiry date can be specified in the aud claim, it is advisable to keep these tokens as short-lived as possible. The recommendation is to set a lifespan of no more than 1 hour. This duration strikes a good balance between security and convenience.