Skip to content
Last updated

API Authentication

All requests to the API require proper authentication.

Here two types of authentication methods for accessing API endpoints are described: Bearer Token Authentication and API Key Authentication.

Authentication Flow

To authenticate, users must send a POST request to the login endpoint with their credentials in the request body. On successful authentication, the server returns a Bearer token.

Authentication process

Bearer authentication (also called token authentication) in use

Authorization: Bearer <token>

To obtain a Bearer token following options present

User authentication process

curl -i -X POST \
  'https://ledger.docs.insly.com/_mock/apis/identifier/swagger/login/{tenant_tag}' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
Response
application/json
{
  "authentication_result": {
    "access_token": "string",
    "expires_in": 0,
    "id_token": "string",
    "refresh_token": "string",
    "token_type": "string"
  },
  "challenge_name": "string",
  "challenge_parameters": {
    "qr_code": "string",
    "required_attributes": [ … ],
    "secret_code": "string",
    "user_attributes": { … },
    "user_id_for_srp": "string"
  },
  "data": {
    "property1": "string",
    "property2": "string"
  }
}

Field Descriptions

OptionTypeDescription
access_tokenstringA token to be used in the Authorization header of subsequent API requests – Bearer token.
expires_inintegerToken validity in seconds (e.g., 3600 = 1 hour).
refresh_tokenstringToken used to obtain a new access_token without re-authentication.

Client authentication process

It is used for application to application connection or integrations.

Important

If you don't have an API key, please contact your partner to get it before making requests using this method.

curl -i -X POST \
  'https://ledger.docs.insly.com/_mock/apis/identifier/swagger/token/client/{tenant_tag}' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "shared_client_id",
    "client_secret": "shared_client_secret",
    "scope": "auth/{tenant_tag}"
  }'

Usage

Once authenticated, include the access_token (Bearer token) in the Authorization header for all subsequent requests

Notes

  • API Key: Ensure the API key is securely stored and transmitted over HTTPS to avoid interception by unauthorized parties.
  • refresh_token should be securely stored to enable token refresh without user login.

General notes

The following Request Headers remain the same throughout the process:

The header of content-type has to be set as application/json ; charset=UTF-8.

Authorization: Bearer {identifier.access_token}
Content-Type: application/json; charset=UTF-8
X-TENANT-ID: {tenant_tag}

In provided examples Authorization: Bearer <YOUR_JWT_HERE> equal to Authorization: Bearer {identifier.access_token}.

Previous page
Next page