# Download OpenAPI

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

The OpenAPI file is useful for:

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

### What you can download

| Asset      | Purpose                                      | Format |
| ---------- | -------------------------------------------- | ------ |
| OpenAPI v1 | Full REST specification for public endpoints | JSON   |

#### Download

* **OpenAPI v1 (JSON):** <https://api.test.devs.beadpay.io/openapi/v1.json>

### Base URLs referenced by the specification

| Environment | REST API base URL                  |
| ----------- | ---------------------------------- |
| Sandbox     | `https://api.test.devs.beadpay.io` |
| Production  | `https://api.beadpay.io`           |

#### Notes

* Use Sandbox for functional testing and integration QA.
* Use Production for live merchant traffic and settlement.
* Keep Sandbox and Production credentials separate.
* Store environment-specific values in configuration so switching environments is not a code change.

### Authentication notes

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

#### Payments

Payments endpoints use terminal API key authentication.

Send:

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

Important:

* `apiKey` is the usable secret credential
* `maskedApiKey` is not usable

#### Onboarding and related administrative APIs

Use the authentication method documented on the specific product-area page. Where onboarding and related admin/entity-management guides show API key authentication, send:

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

Do not assume a single authentication method applies to every Bead API. Always follow the documentation for the endpoint family you are using.

### Working with the OpenAPI file

You can use the OpenAPI specification to:

* inspect available paths and methods
* review required headers and request bodies
* confirm response models and status codes
* generate SDKs or typed clients with your preferred tooling
* import the file into internal API tools that support OpenAPI

### Versioning and updates

| Topic                  | Guidance                                                                                |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Spec version           | OpenAPI v1 is the current public specification                                          |
| Backward compatibility | Breaking changes are announced on the Changelog and communicated to registered partners |
| Refresh cadence        | Re-download the OpenAPI file when you see a relevant update on the Changelog            |

### Troubleshooting

| Symptom                                          | Likely cause                                | Fix                                                                                        |
| ------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Generated client does not match current behavior | Local spec file is outdated                 | Download the latest OpenAPI file again                                                     |
| 401 on API requests                              | Wrong credential type or invalid credential | Confirm the authentication method for that API family and verify the credential being sent |
| 404 on a known endpoint                          | Wrong base URL or environment               | Confirm you are using the correct Sandbox or Production host                               |
| Validation errors on request bodies              | Request shape does not match schema         | Compare your request body against the OpenAPI model and required fields                    |

### Next steps

| Action                                      | Where                                                                        |
| ------------------------------------------- | ---------------------------------------------------------------------------- |
| Review shared conventions and auth guidance | [Reference Guide](https://developers.bead.xyz/reference-guide)               |
| Explore methods and paths                   | [Endpoint Index](https://developers.bead.xyz/reference-guide/endpoint-index) |
| Review onboarding workflows                 | [Onboarding](https://developers.bead.xyz/onboarding)                         |
| Review payment workflows                    | [Payments](https://developers.bead.xyz/payments)                             |
| See recent API changes                      | [Changelog](https://developers.bead.xyz/changelog)                           |