Authentication

All Bead APIs require an OAuth 2.0 access token using OpenID Connect. Today Bead supports the password grant for integrators. Tokens include a refresh token so you can renew access without re authenticating the user.

Clients

Two OAuth clients are available for API integrations.

• bead-terminal Use this client_id for Payments, including creating payments, using the hosted payment page, and calling status or polling endpoints.

• bead-integrator Use this client_id for Onboarding and Entity Management APIs.

Your Bead contact will confirm which client to use for each environment.

Token endpoint

All token requests are sent to the OpenID Connect token endpoint.

Endpoint format

POST {identity_base_url}/realms/{realm}/protocol/openid-connect/token

Header

Content-Type: application/x-www-form-urlencoded

Placeholders

• identity_base_url Identity host for your environment. For Bead this is typically https://identity.beadpay.io

• realm Realm for your environment. Bead currently uses

  • nonprod for Sandbox and other non production environments

  • prod for Production

Examples

• Non production https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token

• Production https://identity.beadpay.io/realms/prod/protocol/openid-connect/token

For a full list of environment hosts and API base URLs, see Environments and Base URLs in the Reference Guide.

Password grant request for Payments (bead-terminal)

Use the bead-terminal client when calling Payments APIs.

Fields

• grant_type=password

• client_id=bead-terminal

• client_secret if required for your deployment

• username

• password

Example curl

curl -s -X POST "{identity_base_url}/realms/{realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=bead-terminal" \
  -d "username={username}" \
  -d "password={password}"

Replace {identity_base_url} and {realm} with the correct values for your environment, for example the nonprod or prod URLs shown above.

Password grant request for Onboarding and Entity Management (bead-integrator)

Use the bead-integrator client when calling Onboarding and Entity Management APIs.

Fields

• grant_type=password

• client_id=bead-integrator

• client_secret if required for your deployment

• username

• password

Example curl

curl -s -X POST "{identity_base_url}/realms/{realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=bead-integrator" \
  -d "username={username}" \
  -d "password={password}"

Use the same token endpoint format and realm values as in the previous section.

Typical token response

A successful token request returns a JSON object similar to the following.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800,
  "refresh_expires_in": 2592000,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Key fields

• access_token JWT that must be sent as a Bearer token on API calls.

• expires_in Lifetime of the access token in seconds. Renew before it expires.

• refresh_token Long lived token used to obtain new access tokens.

• refresh_expires_in Lifetime of the refresh token in seconds.

• token_type Always Bearer.

Store tokens securely and avoid logging full token values in plain text.

Refresh token request

Use the refresh token grant to obtain a new access token without prompting the user for credentials again.

Fields

• grant_type=refresh_token

• client_id Use the same client as the original token, either bead-terminal or bead-integrator.

• refresh_token The refresh token value from the previous token response.

Example curl

curl -s -X POST "{identity_base_url}/realms/{realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=bead-integrator" \
  -d "refresh_token={refresh_token}"

The response has the same structure as the original token response and typically includes new access and refresh tokens.

Using the access token

Add the access token as an Authorization header on every API call.

Authorization: Bearer {access_token}

Examples

• Payments GET https://api.test.devs.beadpay.io/Merchants/{id}/payments

• Onboarding POST https://api.test.devs.beadpay.io/merchant-onboarding/application

• Settlement GET https://api.test.devs.beadpay.io/MerchantSettlements/merchant/{merchantId}

The same token can be used across Payments, Onboarding, Entity Management, Settlement, and Reporting within the scope of the configured client and realm.

Optional scopes

Scopes are not required for core API calls.

• Include scope=openid only if you need an ID token or plan to call a user info endpoint.

• Include profile or email only if you actually consume those claims in a portal or user facing application.

If you do not need identity claims, omit the scope parameter and treat the token as a pure API access token.

Operational notes

Recommended practices when working with tokens

• Refresh a few minutes before expires_in to avoid clock skew issues between your systems and the identity provider.

• Store refresh tokens securely and rotate credentials on a regular schedule.

• Use TLS for all token and API requests and treat both access tokens and refresh tokens as secrets.

• Avoid embedding tokens in URLs or logs. Use headers and structured logging instead.

• Prefer short lived access tokens and rely on refresh tokens rather than issuing very long lived access tokens.

Next steps

After you can successfully obtain and refresh tokens:

• Follow Quick Start to create a payment, present the hosted page, and confirm status.

• Use the Onboarding section to submit an application, automatically email the signer, and track status through approval.

• Use Entity Management to add merchants, locations, and terminals after approval.

• Use Reporting and Settlement once you are ready to build history, reconciliation, and settlement views.