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.
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-----
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>"
}
- The
iss
claim is always fixed tologinid.io
- For the
aud
claim, use the hostname of your tenant base URL. For instance, if your tenant base URL ishttps://qrtg4rxycm0mqet-uicunq.gen2.playground.loginid.io
, then the hostname would beqrtg4rxycm0mqet-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.