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.

Default hosts

By default, Insly provides the following host patterns for tenant environments:

Development (Beta) https://{tenant}.app.beta.insly.training/ (region: eu-west-1, Ireland)

Client testing (Demo)

https://{tenant}.app.demo.insly.com/ (region: eu-west-1, Ireland)

Production (Prod)

https://{tenant}.app.insly.com/ (region: eu-west-1, Ireland)

https://{tenant}.app.us.insly.com/ (region: us-west-2, Oregon)

https://{tenant}.app.za.insly.com/ (region: af-south-1, Cape Town)

https://{tenant}.app.au.insly.com/ (region: ap-southeast-2, Sydney)

where {tenant} is the tenant's unique name.

It's also possible to configure a custom tenant domain, e.g. app.client-domain.co.uk.

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

Option	Type	Description
`access_token`	string	A token to be used in the `Authorization` header of subsequent API requests – Bearer token.
`expires_in`	integer	Token validity in seconds (e.g., 3600 = 1 hour).
`refresh_token`	string	Token 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}.