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:

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:

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
Explore methods and paths	Endpoint Index
Review onboarding workflows	Onboarding
Review payment workflows	Payments
See recent API changes	Changelog