Core Concepts

This page orients you to the cross cutting rules that apply to every Bead API. Each topic has its own detail page. The summaries below tell you when to click through.

Environments and base URLs

Sandbox and production hosts, ports, TLS requirements, health check endpoints, and how to switch between environments without code changes.

See the Environments & Base URLs page in the Reference Guide for the full table of:

• REST API base URLs for Sandbox and Production

• OAuth token URLs for each realm (nonprod and prod)

• Health check endpoints and connectivity notes

Authentication and OAuth 2.0

How to obtain and refresh access tokens for the Bead APIs.

The Authentication page covers:

• OAuth 2 password grant flow

• Realms used by Bead (nonprod for Sandbox and other non production environments, prod for Production)

• Which client to use (bead-terminal for Payments, bead-integrator for Onboarding and Entity Management)

• Token response fields, expiry, and refresh token usage

• Example curl requests and common error conditions

Use this when you are wiring up token acquisition or troubleshooting authorization failures.

Error codes

Standard error response format and how to decide when to retry versus fail fast.

The Error Codes page describes:

• The standard JSON error object shape

• How HTTP status codes map to fault categories

• Which errors are safe to retry, such as transient 5xx and 429 with backoff

• Examples of validation errors (400), authentication issues (401 or 403), and not found conditions (404)

Use this when building error handling, logging, and alerting for your integration.