Authentication

Bead APIs use OAuth2 for secure authentication. There are two different OAuth2 flows depending on the API category you are accessing:

Flow 1: Terminal-based Authentication (Payments & Status APIs)

Used primarily for initiating payments, checking payment status, and configuring webhooks.

Endpoint:

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

Authentication Request (Terminal-based):

POST https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
client_id=bead-terminal
username={terminalId}@beadpay.io
password={terminalPassword}
scope=openid profile email

Response Example:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use this token as a bearer token in your requests:

Authorization: Bearer {access_token}

Flow 2: Username & Password Authentication (Boarding, Settlement, Reporting APIs)

For Boarding, Settlement, Reporting, and similar APIs, use your provided integration credentials (username/password).

Endpoint:

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

Authentication Request (Username & Password):

POST https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
client_id=bead-integrator
username={your_username}
password={your_password}
scope=openid profile email

Response Example:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Similarly, use this token as a bearer token in your requests:

Authorization: Bearer {access_token}

Best Practices

  • Always use HTTPS when making OAuth2 requests.

  • Store your tokens securely. Do not expose tokens publicly or in client-side code.

  • Refresh tokens proactively to avoid downtime due to expired tokens.

Next Steps

PreviousQuick StartNextPayments

Last updated