Authentication

All Bead APIs require an OAuth 2.0 access token (OIDC). Today we support the password grant for integrators. Tokens include a refresh token so you can renew without re-authenticating the user.

Clients

• bead-terminal — use this client_id for Payments (create payments, hosted payment page, status/polling)

• bead-integrator — use this client_id for Onboarding and Entity Management

Token endpoint

POST {identity_base_url}/realms/{realm}/protocol/openid-connect/token Content-Type: application/x-www-form-urlencoded

Placeholders

• identity_base_url — your identity host

• realm — the realm for your environment

Password grant request (Payments: bead-terminal)

Fields

• grant_type=password

• client_id=bead-terminal

• client_secret (if applicable)

• username

• password

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=password" \
  -d "client_id=bead-terminal" \
  -d "username={username}" \
  -d "password={password}"

Password grant request (Onboarding & Entity Management: bead-integrator)

Fields

• grant_type=password

• client_id=bead-integrator

• client_secret (if applicable)

• username

• password

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=password" \
  -d "client_id=bead-integrator" \
  -d "username={username}" \
  -d "password={password}"

Typical token response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800,
  "refresh_expires_in": 2592000,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Refresh token request (either client)

Fields

• grant_type=refresh_token

• client_id (use the same client as the original 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=bead-integrator" \
  -d "refresh_token={refresh_token}"

Using the access token

Add this header on every API call: Authorization: Bearer {access_token}

Optional scopes

Scopes are not required for API calls. Include scope=openid only if you need an ID token or to call a user info endpoint; profile and email are only useful if you actually consume those claims in a portal or user-facing app.

Operational notes

• Tokens expire; refresh a few minutes before expires_in to avoid clock-skew issues.

• Store refresh_token securely and rotate credentials regularly.

• Use TLS for all requests and treat tokens as secrets.

Next steps

• Payments: create a payment, present the hosted page, confirm status.

• Onboarding: submit an application, auto-email the signer, track status.

• Entity Management: manage merchants, locations, and terminals.