# Reference Guide

This guide defines shared patterns used across Bead APIs, including authentication, headers, pagination, errors, field formats, and discovery. Use it alongside the Endpoint Index and the product area guides.

### Quick links

| Topic                      | Where                                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Environments and base URLs | This page, [Environments at a glance](#environments-at-a-glance)                                                    |
| Download OpenAPI           | [Download OpenAPI](/reference-guide/endpoint-index/download-openapi.md)                                             |
| Endpoint Index             | This page, [Endpoint Index](/reference-guide/endpoint-index.md)                                                     |
| Authentication             | This page, [Authentication at a glance](#authentication-at-a-glance)                                                |
| Tender Types               | [Payments](/payments.md), [Tender Types](/reference-guide/enumerations-and-schemas/tender-types.md)                 |
| Payment History concepts   | [Reporting](/reporting.md), [Payment History](/reporting/payment-history-concepts.md)                               |
| Rate limits and retries    | This page, [Rate limits and retries](/reference-guide/core-concepts/rate-limits-and-throttling.md)                  |
| Error model                | This page, [Error model](/reference-guide/core-concepts/error-codes.md)                                             |
| Webhook Event Reference    | [Payments](/payments.md), [Webhook Event Reference](/reference-guide/operational-guides/webhook-event-reference.md) |

### Environments at a glance

| Environment | Purpose                               | REST API base URL                  | OAuth token URL\*                                                          |
| ----------- | ------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
| Sandbox     | Functional testing and integration QA | `https://api.test.devs.beadpay.io` | `https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token` |
| Production  | Live merchant traffic and settlement  | `https://api.beadpay.io`           | `https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token` |

\* Only for endpoint families that explicitly require OAuth.

#### Notes

* Use the correct realm per environment. Your Bead contact will confirm the realm values you should use for Sandbox and Production.
* Keep base URLs and credentials in configuration so switching environments is a deploy-time change, not a code change.
* Keep Sandbox and Production credentials separate.

### Authentication at a glance

Bead supports multiple authentication methods depending on the API family you are calling.

| API family                                            | Preferred auth   | Required header                        | Notes                                                                             |
| ----------------------------------------------------- | ---------------- | -------------------------------------- | --------------------------------------------------------------------------------- |
| Payments                                              | Terminal API key | `X-Api-Key: {apiKey}`                  | Use the full `apiKey` value. `maskedApiKey` is not usable.                        |
| Onboarding                                            | API key          | `X-Api-Key: {apiKey}`                  | Use API key authentication for onboarding requests.                               |
| Entity Management and related admin/entity operations | API key          | `X-Api-Key: {apiKey}`                  | Use API key authentication where the product-area docs show `X-Api-Key`.          |
| Endpoint families that explicitly require OAuth       | OAuth 2.0        | `Authorization: Bearer {access_token}` | Only use OAuth where the endpoint family or product-area page explicitly says so. |

### Standard headers

Use these headers unless an endpoint states otherwise.

| Header         | Value                                            |
| -------------- | ------------------------------------------------ |
| `Content-Type` | `application/json` for requests with JSON bodies |
| `Accept`       | `application/json`                               |

### API key example headers

| Header         | Value              |
| -------------- | ------------------ |
| `X-Api-Key`    | `{apiKey}`         |
| `Content-Type` | `application/json` |
| `Accept`       | `application/json` |

#### Example curl

```bash
curl -s -X GET "https://api.test.devs.beadpay.io/merchant-onboarding/applications/{applicationId}" \
  -H "Accept: application/json" \
  -H "X-Api-Key: {apiKey}"
```

### OAuth guidance

Some Bead endpoint families may still require OAuth. When OAuth applies, follow the authentication instructions on that specific product-area or endpoint-family page.

#### Token endpoint format

`POST https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token`

#### Standard OAuth request header

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

#### Bearer token header

`Authorization: Bearer {access_token}`

#### Important note

Do not assume OAuth is required for every Bead API. Use the authentication method documented for the product area you are integrating with.

### Conventions

Shared rules for timestamps, identifiers, pagination, errors, and discovery.

#### Timestamps

| Topic    | Convention                                            |
| -------- | ----------------------------------------------------- |
| Format   | ISO 8601 in UTC with `Z` suffix                       |
| Examples | `2025-09-02T16:22:11Z`, `2025-09-02T16:22:11.015Z`    |
| Fields   | `created`, `updated`, and similar date fields use UTC |

#### Identifiers and casing

| Topic            | Convention                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------- |
| IDs              | Treat IDs as opaque strings                                                                  |
| Case sensitivity | Enum values and IDs are case sensitive                                                       |
| Immutability     | IDs and server-managed timestamps are read-only unless an endpoint explicitly says otherwise |

#### Pagination

Many list endpoints use `page` and `pageSize`.

| Parameter  | Type    | Notes                                                                 |
| ---------- | ------- | --------------------------------------------------------------------- |
| `page`     | integer | Follow the numbering and defaults documented on the specific endpoint |
| `pageSize` | integer | Page size                                                             |

#### Pagination notes

* Some endpoints return paginated envelopes.
* Some list endpoints return a bare array when the full set is expected to be small.
* Always follow the specific endpoint schema and examples for paging behavior.

#### Error model

Error responses follow the schema documented for the endpoint or API family.

General guidance:

* Surface the human-readable message to end users when appropriate.
* Log trace or correlation identifiers when present.
* Preserve field-level validation details when available.

#### HTTP status codes

| Status | When                                 |
| ------ | ------------------------------------ |
| `200`  | Successful read or update            |
| `201`  | Resource created                     |
| `202`  | Accepted for asynchronous processing |
| `204`  | Successful delete with no body       |
| `400`  | Invalid input or request shape       |
| `401`  | Missing or invalid credential        |
| `403`  | Authenticated but not permitted      |
| `404`  | Resource not found                   |
| `409`  | Duplicate or state conflict          |
| `422`  | Business rule failure                |
| `500`  | Unexpected server error              |

### Amounts and currencies

| Topic          | Convention                                                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Numeric fields | Use JSON numbers unless an endpoint explicitly documents otherwise                                                                |
| Precision      | Follow the precision documented for the field or tender                                                                           |
| Currency       | If a field requires a currency, it is documented next to that field; otherwise it may be implied by the merchant, rail, or tender |

### Tender types and enums

| Topic               | Convention                                                                                    |
| ------------------- | --------------------------------------------------------------------------------------------- |
| Tender types        | Use the exact strings shown on the Tender Types pages                                         |
| Case and separators | Values are case sensitive. Copy them exactly as shown                                         |
| Future expansion    | New enum values can appear without a version change. Ignore unknown values when safe to do so |

### Rate limits and retries

| Topic       | Guidance                                                                  |
| ----------- | ------------------------------------------------------------------------- |
| Retries     | Use exponential backoff on `429` and transient `5xx` responses            |
| Headers     | Respect any retry, quota, or remaining-limit headers if returned          |
| Idempotency | If an endpoint supports idempotency keys, that endpoint page will note it |

### Download OpenAPI

Use the download page to retrieve the latest OpenAPI specification in JSON format.

The OpenAPI file is useful for:

* generating clients
* validating requests and responses
* aligning internal tooling with the current public schema
* reviewing available paths, request bodies, and response models

### Discovery and next steps

| Action                                    | Where                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Explore paths and methods                 | [Reference Guide](/reference-guide.md), [Endpoint Index](/reference-guide/endpoint-index.md)                        |
| Download the OpenAPI specification        | [Download OpenAPI](/reference-guide/endpoint-index/download-openapi.md)                                             |
| Review webhook event types and signatures | [Payments](/payments.md), [Webhook Event Reference](/reference-guide/operational-guides/webhook-event-reference.md) |
| Learn payment history filters and paging  | [Reporting](/reporting.md), [Payment History Concepts](/reporting/payment-history-concepts.md)                      |
| See changes by area and date              | [Changelog](/changelog.md)                                                                                          |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/reference-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.