Authentication & OAuth 2.0

Most integrators should not need this page. The preferred authentication method across current Bead API families is an API key sent in the X-Api-Key header. Payments always uses the terminal API key in X-Api-Key; it does not use OAuth or a username and password. See Authentication for the current, API key first guidance and examples.

This page documents the OAuth 2.0 password grant model used by Boarding and Entity Management. It applies to existing integrations that were provisioned with OAuth credentials before API key authentication was available, and to any endpoint that specifically requires OAuth. If you are starting a new integration and have not been given OAuth client credentials, use X-Api-Key instead and you can skip this page entirely.

Existing OAuth integrations obtain an access token, then send it on every request. Use separate credentials for Test and Production.

Token endpoints

Environment	OAuth token URL
Test / Non-prod	https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token
Production	https://identity.beadpay.io/realms/prod/protocol/openid-connect/token

Token endpoint pattern used for all realms:

{OIDC_BASE}/protocol/openid-connect/token

Headers

Header	Value
Authorization	Bearer <access_token>
Content-Type	application/json for requests with bodies
Accept	application/json

Integration identity at a glance

This describes the legacy OAuth model still supported for existing integrations. New integrations should use API key authentication and can skip this table.

Model	Client ID	Credential subject	Grant type	Token cache key	Latency posture
Boarding and Entity Management (legacy)	Boarding client	Single integrator username and password	Password grant	clientId, usually a single token is sufficient	Latency is secondary and auditability is primary

Token types and lifetimes

Token	Typical lifetime	How it is used
Access token	3600 seconds	Sent on every API call in Authorization: Bearer <access_token>
Refresh token	36000 seconds	Exchanged for a new access token and a new refresh token

Lifetimes can vary by environment and client. Always honor expires_in and refresh_expires_in returned by the token endpoint.

Standard policy for the legacy OAuth model

• Cache the access token and refresh two to five minutes before expiry

• If an API call returns 401 Unauthorized, perform one refresh and retry once

• Always store the newest refresh token that the identity server returns

• If refresh fails with invalid_grant or the refresh token is expired, perform a full sign in

• Keep tokens on the server only, do not log tokens, encrypt at rest if persisted

• In multi-process or multi-worker apps, ensure only one worker performs the refresh and others reuse the result

Boarding and entity management (legacy OAuth path)

Goal: safe and auditable operations where latency is less critical.

• Use the same refresh and 401 retry rules with a larger pre-expiry buffer

• A single service level token is usually sufficient for administrative workloads

• Emphasize least privilege scopes and clear audit logging of who did what and when

Payments does not use OAuth

Payments requests authenticate with the terminal API key in the X-Api-Key header. Do not request OAuth tokens for Payments, and do not look for a terminal username and password. See Authentication.

Why use refresh tokens

Security and reliability:

• Renew access without resending primary credentials

• Identity can revoke a refresh token family to cut off access quickly

• Each refresh issues a fresh access token so roles and scopes remain current

Performance:

• One light refresh call is faster and cheaper than a full sign in

• Fewer round trips and fewer failures under load

Minimal refresh decision logic

Proactive, before calling an API:

• If now >= issued_at + expires_in - buffer then refresh

• Otherwise use the cached access token. Suggested buffer is 120 to 300 seconds with small random jitter in high volume systems

Reactive fallback on failure:

• If a request returns 401 and you have not just refreshed, perform one refresh and retry once

• If it still fails, perform a full sign in and alert

Grant types

Choose the grant type you were provisioned for. Fields use standard OpenID Connect names. Send each request as POST to the token endpoint with Content-Type: application/x-www-form-urlencoded. To target Production, use the prod realm instead of nonprod.

Password grant fields

Field	Value
grant_type	password
client_id	Your provisioned client ID
username	Your integrator username
password	Your integrator credential
scope	openid profile email

Refresh token grant fields

Field	Value
grant_type	refresh_token
client_id	Your provisioned client ID
refresh_token	The latest refresh token

Token response

{
  "access_token": "<jwt>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "<refreshToken-when-present>",
  "scope": "openid profile email"
}

Using tokens

Send the access token on every API call in the Authorization header as Bearer <access_token>.

Next steps

• See Authentication for current, API key first authentication guidance across all API families.

• See Where do I find the base URLs, realm, and client IDs? if you are on the legacy OAuth path and need realm or client ID values.