Overview

​

Authentication & Authorization

OwnID’s APIs utilize JWT access tokens for authentication and authorization. An access token is required to be passed with most API requests. The token should be included in the Authorization header of your HTTP request as a Bearer token:

Authorization: Bearer <access_token>

Access tokens are generated after successful authentication and contain key details used to identify and authorize the caller.

​

Authentication

The JWT is authenticated through its signature, ensuring it has not been tampered with. Each JWT is signed using a secure algorithm and verified using a secret key or public key.

​

Authorization

The JWT payload contains authorization details that determine what actions the token bearer is allowed to perform. These details are critical to enforcing permission policies on the API.

​

Access Tokens

Access tokens used by OwnID are signed JWTs (JSON Web Tokens). These tokens encapsulate the following key information:

• Authentication: Verified via the JWT’s signature.
• Target user: Defined in the payload’s sub (subject), which typically corresponds to the user’s loginId.
• Authorization: Defined by the authorization details within the payload, which may specify various claims and permissions.

​

JWT Structure

The JWT consists of three parts:

1. Header: Contains metadata about the type of token and the signing algorithm used.
2. Payload: Contains the claims, including:
   • sub: The subject or user identifier (usually the login ID).
   • authorization details: Claims that define the permissions granted to the token holder.
3. Signature: Ensures the integrity of the token and verifies that it has not been altered.

​

For End-Users (Customers)

For end-user authentication, the JWT access token is generated after passing a series of authentication steps, such as multi-factor authentication (MFA) or other challenges. Once authenticated, the token can be used to make authorized requests on behalf of the user.

Example process:

1. User completes authentication (e.g., login).
2. Upon successful authentication, an access token is generated and returned.
3. The client can then use this token in the Authorization header of API requests.

​

For Admin-Users / Server-to-Server Calls

For admin users and server-to-server communication, the JWT access token can be created and signed using a signing key. The token will include specific fields like kid (key ID) and iss (issuer) to identify the key and issuer used for signing.

These tokens allow for more extensive permissions and can be used to manage and control various aspects of the OwnID platform through the Admin API.

Example process:

1. A signing key is issued via the OwnID Admin Console.
2. The access token is generated using this key.
3. Admin or server-to-server operations are performed using this token.

​

Getting a Signing Key for Admin-Users

To generate access tokens for server-to-server interactions, you must first obtain a signing key from the OwnID Admin Console. Follow these steps:

1. Log in to the OwnID Admin Console.
2. Navigate to the API Keys section.
3. Create or view an existing signing key.
4. Use this signing key to sign JWT access tokens for admin or server-to-server API calls.

The key will include a key ID (kid) and issuer (iss), which will be included in the JWT header for verification purposes.

​

Using the API

Once you have an access token, you can make API requests to OwnID’s server endpoints. Include the access token in the Authorization header as a Bearer token.

Authorization: Bearer <access_token>

Each API request will validate the token’s signature and ensure that the token has the required permissions for the requested operation based on the JWT’s authorization claims.