Authentication & OAuth 2.0

Obtain an OAuth 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 identities at a glance

Model	Client ID	Credential subject	Grant type	Token cache key	Latency posture
Payments	Payments client	Terminal username and password such as [email protected]	Password grant	terminalId or clientId + merchantId + terminalId	Optimize for low latency and high volume
Boarding and Entity Management	Boarding client	Single integrator username and password	Password grant	clientId and 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 both models

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

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

3. Always store the newest refresh token that the identity server returns

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

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

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

Payments integration

Goal Fast and reliable requests at scale without authenticating on the hot path

• Do not call the token endpoint per transaction

• Maintain a shared token cache keyed by terminalId or by clientId + merchantId + terminalId

• Refresh proactively with a small buffer and jitter so many tokens do not refresh at the same second

• Use a leader process to perform the refresh and fan out the new pair to workers

• Warm the cache for your busiest terminals at service start or during off-peak windows

• Only do a full sign in if refresh fails

Boarding and entity management

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

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

1. If now >= issued_at + expires_in − buffer then refresh

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

Reactive fallback on failure

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

2. 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.

Password grant

curl -X POST "https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=<clientId>" \
  -d "username=<username>" \
  -d "password=<password>" \
  -d "scope=openid profile email"

To target Production, change nonprod to prod.

Refresh token grant

curl -X POST "https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=<clientId>" \
  -d "refresh_token=<refreshToken>"

Swap nonprod to prod to refresh in Production.

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>.