Authentication

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

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}

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

• Payments

• Boarding

• Settlement

• Reporting

For questions about authentication or credentials, reach out to [e-mail].