Environments & Base URLs

Environments and Base URLs

Use the correct environment hosts and identity realm before making API calls. This page keeps the values abstract with examples; replace placeholders with the values provided for your account.

Environments

• Sandbox Used for development and integration testing.

• Production Used for live traffic after certification.

Base URLs

Environment	API base URL	Identity base URL	Onboarding UI (signing)
Sandbox	{sandbox_api_base} (for example, https://api.test.devs.beadpay.io)	{sandbox_identity_base} (for example, https://identity.beadpay.io)	{sandbox_onboarding_ui} (for example, https://onboard.beadpay.io)
Production	{prod_api_base}	{prod_identity_base}	{prod_onboarding_ui}

Notes

• The example hosts are illustrative; use the exact values you were issued.

• If your organization uses region-specific hosts or allowlists, confirm those with your Bead contact.

Identity realms

You will be assigned a realm per environment. Replace {realm} in token requests with the value you were issued.

• Sandbox realm: {sandbox_realm}

• Production realm: {prod_realm}

Token endpoint pattern

All token requests use the OIDC token endpoint.

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

This matches the Authentication page and works for both bead-terminal (Payments) and bead-integrator (Onboarding and Entity Management).

Time, format, and conventions

• JSON for request and response bodies

• ISO 8601 timestamps in UTC

• Idempotency keys recommended on POSTs you may retry

• Standardized error envelopes with a type, title, status, and trace identifier

Connectivity and security

• HTTPS required with modern TLS

• If your environment enforces IP allowlists, provide your egress IPs to your Bead contact

• Keep access tokens and refresh tokens secret; never log full token values

Quick checks before calling APIs

• You can obtain an access token in Sandbox using your assigned realm and client_id

• Your base URLs match the environment you are targeting

• Your firewall allows outbound HTTPS to the API, Identity, and Onboarding UI hosts

Next steps

• Authenticate using the password grant with your assigned client

• Follow Quick Start to create a payment or submit an onboarding application