> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/authentication.md).

# Authentication

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

For current integrations:

* **Payments API** uses a terminal API key sent in the `X-Api-Key` header
* **Onboarding API** uses a partner API key sent in the `X-Api-Key` header
* **Other Bead APIs** may use OAuth 2.0 Bearer tokens depending on the product area and endpoint family

There is no username and password authentication for Payments. All terminal payment requests authenticate with the terminal API key in the `X-Api-Key` header.

If you are unsure which authentication method applies to your use case, ask your Bead contact.

### When to use each authentication method

* **Payments API**: use the terminal API key in the `X-Api-Key` header
* **Onboarding API**: use your partner API key in the `X-Api-Key` header
* **Other Bead APIs**: follow the authentication requirements documented for that API family or endpoint

### Payments authentication: terminal API key

A terminal API key is the secret credential used to authenticate Payments requests for a terminal. You must send the full API key value on each request in the `X-Api-Key` header.

The masked API key is a display value only and cannot be used to authenticate.

#### Required request header

```http
X-Api-Key: {apiKey}
```

For JSON requests, also send:

```http
Content-Type: application/json
```

#### Example curl (Payments)

```bash
curl -s -X POST "{BASE_URL}/Payments" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {apiKey}" \
  -d '{
    "merchantId": "{merchantId}",
    "terminalId": "{terminalId}",
    "requestedAmount": 25.00,
    "reference": "ORDER123"
  }'
```

`POST /Payments/crypto` is deprecated but still supported, and uses the same `X-Api-Key` authentication. Use `POST /Payments` for new work.

#### How to obtain a terminal API key

The full terminal API key is returned only by the calls that create or issue it:

* `POST /Terminals` returns the full key in `apiKey.secret` when the terminal is created.
* `POST /Terminals/{id}/api-keys` issues a new key and returns it in `apiKey.secret`. This is the only way to obtain a key for a terminal that already exists, including the default terminals created when a merchant is boarded.

`GET /Terminals/{id}` and `GET /Terminals` never return a usable key to an integration. They return only the masked value in `apiKey.maskedSecret`, and `apiKey.secret` is empty.

Resetting a key invalidates the previous key immediately, so update every system that uses the terminal before or as you reset it. Store the new key as soon as you receive it. See [Reset Terminal API Key](https://developers.bead.xyz/entity-management/terminal-management/reset-terminal-api-key.md).

#### Payments API key notes

* Treat the API key like a password
* Store it in a secret manager or environment variable
* Do not log the full value
* If you believe an API key is exposed, reset it immediately with `POST /Terminals/{id}/api-keys`

#### Payments troubleshooting

* `401 Unauthorized`: the API key is missing, invalid, masked, replaced by a reset, or sent using the wrong header name. The header must be exactly `X-Api-Key`.
* If you try OAuth flows such as `client_credentials` for `POST /Payments`, you may see errors like `Public client not allowed to retrieve service account`. Payments authentication for that endpoint uses `X-Api-Key`.

### Onboarding authentication: API key

Onboarding requests use a partner API key sent in the `X-Api-Key` header.

#### Required request header

```http
X-Api-Key: {apiKey}
```

For JSON requests, also send:

```http
Content-Type: application/json
Accept: application/json
```

#### Current onboarding request guidance

Use the API key header model for onboarding requests.

Do not send deprecated `apiKey` fields in onboarding request bodies.

For the current onboarding request model:

* **Full application** requests use `signer` and `merchantData`
* **Minimal application** requests use `signerName` and `signerEmail`
* Onboarding create requests require `cryptoEnvironment`

#### Current onboarding create endpoints

```http
POST /merchant-onboarding/applications
POST /merchant-onboarding/applications-short
```

#### Onboarding environment note

For onboarding create requests, set `cryptoEnvironment` to match the environment you are targeting:

* `sandbox` in Sandbox
* `production` in Production

#### Transition note

Legacy bearer-token authentication may still work in some environments during migration, but new integrations should use API key authentication consistently across the Onboarding APIs.

### OAuth token endpoint (OpenID Connect)

OAuth access tokens are used by Bead APIs and endpoints that require OAuth authentication. Payments does not use OAuth.

#### Endpoint format

```http
POST {identity_base_url}/realms/{realm}/protocol/openid-connect/token
```

#### Required header

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

#### Placeholders

* `identity_base_url`: typically `https://identity.beadpay.io`
* `realm`: environment realm
  * `nonprod` for Sandbox and other non-production environments
  * `prod` for Production

#### Common token URL examples

```
https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token
https://identity.beadpay.io/realms/prod/protocol/openid-connect/token
```

### Typical token response (OAuth)

A successful token request returns a JSON object that includes fields such as:

* `access_token`
* `expires_in`
* `refresh_token`
* `refresh_expires_in`
* `token_type` set to `Bearer`

Store tokens securely and avoid logging full token values in plain text.

### Refresh token request (OAuth)

Use the refresh token grant to obtain a new access token without prompting for credentials again.

#### Fields

* `grant_type=refresh_token`
* `client_id={client_id}`
* `refresh_token={refresh_token}`

#### Example curl

```bash
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={client_id}" \
  -d "refresh_token={refresh_token}"
```

### Using an OAuth access token

Add the access token as an `Authorization` header on every request to APIs that require OAuth authentication.

```http
Authorization: Bearer {access_token}
```

### Optional scopes (OAuth)

Scopes are not required for core API calls.

* Include `scope=openid` only if you need an ID token or plan to call a user info endpoint
* Include `profile` or `email` only if you consume those claims in a portal or user-facing application
* If you do not need identity claims, omit the `scope` parameter and treat the token as a pure API access token

### Quick troubleshooting summary

#### API key requests

* Confirm the header name is exactly `X-Api-Key`
* Confirm you are using the full API key value, not the masked value
* Confirm the key matches the correct environment
* Confirm the key was not replaced by a later reset
* Do not send masked keys or deprecated body fields

#### Onboarding requests

* Use API key auth
* Use the current request shapes, not `signerInfo`
* Set `cryptoEnvironment` correctly
* Keep environment and credentials aligned

#### OAuth requests

* Verify realm selection: `nonprod` vs `prod`
* Verify client and grant type
* Verify access token freshness
* Send the token as `Authorization: Bearer {access_token}`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
