Getting Started

Prepare base URL

Your Issuer API environment is entirely managed by nChain's Product Suite Platform (PSP), so there is nothing to worry about setting up the technology stack. You will receive the Issuer API Base URL for your environment. The Issuer API uses a single base URL to standardize all endpoints.

To check if your Issuer API Base URL is valid, you can visit the Ping-Pong website at GET <BASE_URL>/ping

Authentication

TODO: ApiKey

Authentication for the Issuer API is managed via AWS Cognito using its hosted UI. This ensures secure, standards-compliant access and enables streamlined user authentication workflows.

AWS Cognito Hosted UI

• Users authenticate through a web-based login page provided by Cognito.

• After successful login, a JWT access token is issued. This token must be included in the Authorization header of every API request.

Authentication Flow

Read more about authentication with AWS Cognito on their documentation page here.

• Step 1: Direct the user to the Cognito Hosted UI login page

• Step 2: After successful login, the Cognito Hosted UI redirects the user to the redirect_uri with an authorization code

• Step 3: The client application exchanges the authorization code for an access token by making a POST request to Cognito's token endpoint:

• Step 4: Cognito responds with an access token, which you need to include in the Authorization header for all API requests:

Authorization: Bearer <ACCESS_TOKEN>

Authorization

The Issuer API uses role-based access control (RBAC) to manage permissions. Authorization is enforced using the cognito:groups claim in the JWT access token, which specifies the user’s assigned claims. These permissions determine what actions the user can perform within the API.

Supported Roles

• Issuer Admin - can view and issue verifiable credentials, can view the history of issued credentials, can revoke credentials & more

• Issuer Auditor - can view the history of issued credentials, can revoke credentials & more