Authenticate

Learn how to obtain an access token to authenticate with IDnow's Trust Platform

IDnow's Trust Platform uses OAuth 2.0 with the client credentials grant type for API authentication. The steps to set up authentication are:

1. Create API clients
2. Use the obtained client ID and client secret to get an access token
3. Use the access token to make an authenticated API request

---

Environments and URLs

IDnow's Trust Platform uses two distinct base URLs — make sure to use the correct one for each purpose:

URL	Purpose
https://localhost:3002	Authentication — obtain an access token via /oidc/token
https://localhost:3000	API calls — all business logic endpoints (sessions, flows, results, etc.)

Important: The authentication URL (authUrl) is separate from the API base URL (baseUrl). Using the API base URL for authentication will result in a 404 error.

---

Obtain access token

Use your client ID and client secret to request an access token from the authentication server.

Request parameters

Parameter	Description	Required
grant_type	OAuth 2.0 grant type. Use client_credentials for server-to-server auth.	Yes
client_id	Your API client ID from the Trust Platform Studio.	Yes
client_secret	Your API client secret from the Trust Platform Studio.	Yes

Two authentication methods are supported. Both are equivalent — use whichever fits your HTTP client best.

Credentials in request body (client_secret_post)

Include your credentials directly in the request body:

curl --request POST https://localhost:3002/oidc/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials' \
--data 'client_id=<your-client-id>' \
--data 'client_secret=<your-client-secret>'

Credentials in Authorization header (client_secret_basic)

Encode your credentials as Base64(client_id:client_secret) and pass them in the Authorization header:

curl --request POST https://localhost:3002/oidc/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <base64(client_id:client_secret)>' \
--data 'grant_type=client_credentials'

Response

If successful, you will receive an access token:

{
  "access_token": "eyJh...QifQ.eyJ...hIOw",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Note: The default access token lifetime is typically 86400 seconds (24 hours). Cache tokens appropriately to avoid unnecessary requests.

---

Make an API request

Now that you have a valid access token, you can make requests to Trust Platform's APIs using the API base URL. Include the access token in the Authorization header using the Bearer scheme:

GET /api/v1/<endpoint> HTTP/1.1
Host: localhost:3000
Accept: application/json
Authorization: Bearer eyJh...QifQ.eyJ...hIOw
User-Agent: my-backend-service/1.0

Example request

curl --request GET https://localhost:3000/api/v1/flows/{flowId}/{environment}/sessions \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJh...QifQ.eyJ...hIOw' \
--header 'User-Agent: my-backend-service/1.0'

User-Agent header required

All API requests must include a User-Agent header. Requests without a User-Agent are rejected with 403 Forbidden by the WAF before they reach the API. Set a descriptive value that identifies your integration, for example User-Agent: my-backend-service/1.0.

---

Using an OpenID Connect library

Instead of implementing the token request manually, we recommend using a certified OpenID Connect client library for your language or framework. These libraries handle token fetching, caching, and renewal automatically.

---