Authentication

Every call to the Blerify API — whether for Issuance, Verification, or Trust Registry — authenticates as a service account. This page explains what a service account is, how to create one in the Portal, and how to exchange its credentials for a bearer token you can use on every request.

Prerequisites

• Admin access to the Blerify Portal

What is a service account

A service account is a non-human identity your backend uses to call the Blerify API. It is not tied to any individual login and does not participate in human authentication flows. You can scope a service account to a single product (Issuance, Verification) or give it roles across multiple products at once — the roles you assign determine what the account can actually do. See each product's Portal Roles and Permissions page for the full list of available roles.

Authentication uses the OAuth 2.0 client_credentials grant with private_key_jwt as the client authentication method (RFC 7523). There is no shared client secret. Your service account's private key signs a short-lived JWT assertion; you exchange that assertion for a bearer token.

Create a service account

1. Log in to the Blerify Portal with an admin account.

1. Go to Settings → Service Accounts.

1. Click Create Service Account.

1. Fill in the account details:

   • Name — a descriptive identifier (e.g. payments-integration, kyc-backend)

   • Description — optional; what this account is used for

   • Roles — the permissions this account needs, scoped per product (e.g. verifications.api, credentials.api, notifications.api)

2. Click Create. The Portal generates a credentials JSON file and downloads it immediately. You cannot retrieve this file again — store it securely before closing the dialog.

The credentials file

The downloaded JSON contains everything you need to authenticate:

{
  "type": "service_account",
  "organization_id": "your-organization-id",
  "client_id": "your-client-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "token_uri": "https://...",
  "iam_audience": "https://..."
}

Field	Used for
client_id	Identifies the service account; sent as the client_id form field and used as iss and sub in the JWT assertion
organization_id	Sent as the organization_id form field
private_key	Signs the JWT assertion (RS256)
token_uri	The token endpoint you POST the assertion to — always read this from the file; it can vary by account
iam_audience	The aud claim in the JWT assertion

Keep the private_key secret. Treat the credentials file like a private key — don't commit it to source control, don't expose it in client-side code, and don't log it.

Get an access token

Build a short-lived JWT assertion signed with your private key, then POST it to token_uri.

JWT assertion structure:

// header
{ "alg": "RS256", "typ": "JWT" }

// payload
{
  "iss": "your-client-id",
  "sub": "your-client-id",
  "aud": "your-iam-audience",
  "iat": 1700000000,
  "exp": 1700003600,
  "jti": "a-unique-uuid-v4"
}

The jti must be unique per request — it prevents token replay. Keep the assertion short-lived; one hour is typical.

Token request:

curl -X POST 'https://your-token-uri' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=your-client-id' \
  -d 'organization_id=your-organization-id' \
  -d 'client_assertion=your-signed-jwt'

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 600
}

Read expires_in from the response rather than hardcoding a number — it can vary.

Use a library instead of building from scratch

The official blerify/auth-php-client package handles assertion signing, token caching, and renewal from a credentials JSON file. If you're working in PHP, start there.

Use the token

Include the token in the Authorization header of every API request:

Authorization: Bearer eyJ...

Cache the token and refresh it before expires_in elapses. Requesting a new token on every API call adds latency and will hit rate limits under load.

Next steps

Get Started with Issuance — issue your first credential using a service account with the credentials.api role.

See also: Get Started with Verification · Full endpoint reference at https://dev.blerify.com