Authentication

Bead supports multiple authentication methods depending on the API family you are calling.

Payments (preferred for new integrations) use a terminal API key that you send on each request as a header. OAuth 2.0 access tokens (OpenID Connect) are still supported for existing Payments integrations and are used by other Bead APIs. If you are unsure which method applies to your use case, ask your Bead contact.

Payments authentication (preferred): Terminal API key

A terminal API key is the secret credential used to authenticate Payments requests. You must send the full apiKey value on each request. maskedApiKey is a display value and cannot be used to authenticate.

Required request headers

X-Api-Key: {apiKey} Content-Type: application/json

Example curl (Create a payment)

Replace placeholders with your environment and values.

• {BASE_URL} example: https://api.test.devs.beadpay.io

• {apiKey} example format: term.<...>.<...> (use the full value you were issued)

curl -s -X POST "{BASE_URL}/payments/crypto" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {apiKey}" \
  -d '{
    "merchantId": "{merchantId}",
    "terminalId": "{terminalId}",
    "requestedAmount": {requestedAmount},
    "paymentUrlType": "web",
    "reference": "ORDER123"
  }'

Troubleshooting (API key)

• 401 Unauthorized The API key is missing, invalid, or sent using the wrong header name. The header must be exactly X-Api-Key.

• OAuth errors when calling Payments If you attempt OAuth client_credentials or other OAuth flows, you may see errors such as “Public client not allowed to retrieve service account”. Payments authentication for POST /payments/crypto uses X-Api-Key. Ignore the OAuth path for this endpoint.

Operational notes (API key)

• Treat the apiKey like a password. Store it in a secret manager or environment variable and avoid logging it.

• If you believe an apiKey is exposed, rotate it immediately through your Bead contact and treat prior logs as compromised.

Payments authentication (legacy): OAuth password grant (bead-terminal)

Existing integrators may continue to authenticate Payments using OAuth 2.0 password grant with a terminal username and password. New Payments integrations should use the terminal API key method above.

Use the bead-terminal client when obtaining tokens for legacy Payments integrations.

Password grant request fields (legacy Payments)

• grant_type=password

• client_id=bead-terminal

• username

• password

Example curl (legacy Payments)

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}"

OAuth token endpoint (OpenID Connect)

OAuth access tokens are used by Bead APIs that are not authenticated by terminal API key. The same token endpoint format and realms are also used for legacy Payments integrations.

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

  • 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 environment hosts and base URLs, see Environments & Base URLs in the Reference Guide.

Typical token response (OAuth)

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

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

• 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 (OAuth)

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

Fields

• grant_type=refresh_token

• client_id Use the same client as the original token request

• 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={client_id}" \
  -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 an OAuth access token

Add the access token as an Authorization header on every request to OAuth protected APIs.

Authorization: Bearer {access_token}

Example

curl -s -X GET "{BASE_URL}/MerchantSettlements/merchant/{merchantId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Optional scopes (OAuth)

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