Authentication

Please contact [e-mail] to acquire your authentication credentials.

Overview

This guide provides an overview of how integrators can authenticate to and acquire an access token from our OpenID Connect (OIDC) endpoint using the Resource Owner Password Credentials (ROPC) flow. The ROPC flow allows direct exchange of the user's credentials for an access token and, optionally, an ID token. This flow is suitable for trusted applications, such as those running on secure servers, and is best suited for scenarios where other flows (like Authorization Code) are not feasible.

You can read more about OAuth2 and OIDC here.

Prerequisites

• User credentials: Obtain these from Bead Pay. Alternatively, these can be the username and password you use to log into the portal.

• OpenID Connect token endpoint:

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

  • Non-production: https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token

  • For users familiar with the OIDC protocol, OIDC metadata can be found at:

    • Production: https://identity.beadpay.io/realms/prod/.well-known/openid-configuration

    • Non-production:https://identity.beadpay.io/realms/nonprod/.well-known/openid-configuration

Login

For the most part, integrators will be authenticating on behalf of a Terminal. In this case, the username will be {terminalId}@beadpay.io and the password will be the terminal's password.

POST https://identity.beadpay.io/realms/{nonprod|prod}/protocol/openid-connect/token

Request Headers

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

Body

grant_type=password
client_id=bead-terminal
username=USERNAME
password=PASSWORD
scope=openid profile email

Example curl command:

curl -X POST https://identity.beadpay.io/realms/prod/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" \
     -d "scope=openid profile email"

Response

200

{
  "access_token": "eyJhbGciO...",
  "expires_in": 3600,
  "refresh_expires_in": 36000,
  "refresh_token": "eyJhbGciOiJ...",
  "token_type": "Bearer",
  "scope": "openid profile email"
}

401

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

To access protected endpoints, pass the access token in the Authorization header of the request.

Example API call using curl:

curl -X 'GET' \
  'https://api.test.devs.beadpay.io/currencies' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'

Refresh Token

When the access token expires, the client can use the refresh token to obtain a new access token without requiring the user’s credentials.

Endpoint: https://identity.beadpay.io/realms/{nonprod|prod}/protocol/openid-connect/token

Request Headers:

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

Request Body:

grant_type=refresh_token
client_id=bead-terminal
refresh_token=YOUR_REFRESH_TOKEN

Sample curl Command:

curl -X POST https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=refresh_token" \
     -d "client_id=bead-terminal" \
     -d "refresh_token=YOUR_REFRESH_TOKEN"

Response Example - Refresh Token Flow

Upon success, the server responds with a new access token, and optionally, a new refresh token.

Example Response:

{
    "access_token": "eyJraWQiOiJhN2...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "openid profile email",
    "refresh_token": "def50200f4b..."  // New refresh token
}