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/tokenAuthentication 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 emailResponse 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/tokenAuthentication 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 emailResponse 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
For questions about authentication or credentials, reach out to [email protected].
Last updated