Authentication

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

For current integrations:

• Payments API uses an API key sent in the X-Api-Key header

• Onboarding API uses an API key sent in the X-Api-Key header

• Other Bead APIs may use OAuth 2.0 Bearer tokens depending on the product area and endpoint family

• Legacy Payments integrations may still use OAuth 2.0 password grant with the bead-terminal client

If you are unsure which authentication method applies to your use case, ask your Bead contact.

When to use each authentication method

• Payments API: use an API key in the X-Api-Key header for new integrations

• Onboarding API: use an API key in the X-Api-Key header

• Other Bead APIs: follow the authentication requirements documented for that API family or endpoint

• Legacy Payments integrations: OAuth 2.0 password grant remains supported where already in use

Payments authentication (preferred): API key

A Payments API key is the secret credential used to authenticate Payments requests. You must send the full API key value on each request in the X-Api-Key header.

The masked API key is a display value only and cannot be used to authenticate.

Required request header

X-Api-Key: {apiKey}

For JSON requests, also send:

Content-Type: application/json

Example curl (Payments)

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

Payments API key notes

• Treat the API key like a password

• Store it in a secret manager or environment variable

• Do not log the full value

• If you believe an API key is exposed, rotate it immediately through your Bead contact

Payments troubleshooting

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

• If you try OAuth flows such as client_credentials for POST /Payments/crypto, you may see errors like Public client not allowed to retrieve service account. Payments authentication for that endpoint uses X-Api-Key.

Onboarding authentication: API key

Onboarding requests use an API key sent in the X-Api-Key header.

Required request header

X-Api-Key: {apiKey}

For JSON requests, also send:

Content-Type: application/json
Accept: application/json

Current onboarding request guidance

Use the API key header model for onboarding requests.

Do not send deprecated apiKey fields in onboarding request bodies.

For the current onboarding request model:

• Full application requests use signer and merchantData

• Minimal application requests use signerName and signerEmail

• Onboarding create requests require cryptoEnvironment

Current onboarding create endpoints

POST /merchant-onboarding/applications
POST /merchant-onboarding/applications-short

Onboarding environment note

For onboarding create requests, set cryptoEnvironment to match the environment you are targeting:

• sandbox in Sandbox

• production in Production

Transition note

Legacy bearer-token authentication may still work in some environments during migration, but new integrations should use API key authentication consistently across the Onboarding APIs.

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 API key method above.

Password grant request fields

• 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 and endpoints that require OAuth authentication. 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

Required header

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

Placeholders

• identity_base_url: typically https://identity.beadpay.io

• realm: environment realm

  • nonprod for Sandbox and other non-production environments

  • prod for Production

Common token URL examples

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

Typical token response (OAuth)

A successful token request returns a JSON object that includes fields such as:

• access_token

• expires_in

• refresh_token

• refresh_expires_in

• token_type set to 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={client_id}

• refresh_token={refresh_token}

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

Using an OAuth access token

Add the access token as an Authorization header on every request to APIs that require OAuth authentication.

Authorization: Bearer {access_token}

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

Quick troubleshooting summary

API key requests

• Confirm the header name is exactly X-Api-Key

• Confirm you are using the full API key value

• Confirm the key matches the correct environment

• Do not send masked keys or deprecated body fields

Onboarding requests

• Use API key auth

• Use the current request shapes, not signerInfo

• Set cryptoEnvironment correctly

• Keep environment and credentials aligned

OAuth requests

• Verify realm selection: nonprod vs prod

• Verify client and grant type

• Verify access token freshness

• Send the token as Authorization: Bearer {access_token}