Download OpenAPI / Postman
Use these downloads to explore the API and run calls in Postman. The OpenAPI file is machine readable, and the Postman assets include ready to use environments for Sandbox and Production.
What you can download
OpenAPI v1
Full REST specification for all public endpoints
JSON
Postman Collection
All endpoints with example requests and response bodies
JSON
Postman Environment Sandbox
Variables for Sandbox including base URL and token URL
JSON
Postman Environment Production
Variables for Production including base URL and token URL
JSON
Base URLs used by the assets
Sandbox
https://api.test.devs.beadpay.io
https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token
Production
https://api.beadpay.io
https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token
Note The token path follows OpenID Connect. Your realm value differs by environment. If you are unsure which realm to use, contact your Bead representative.
Quick start in Postman
Download the Postman Collection and the environment for the environment you plan to use.
Import both files into Postman.
Open the imported environment and confirm the variables match your credentials.
Request a token with your OAuth client details and save it in the environment as
access_token.Send any request in the collection. All requests read
{{baseUrl}}and{{access_token}}from the active environment.
Environment variables included
baseUrl
Host for API requests
https://api.test.devs.beadpay.io
https://api.beadpay.io
tokenUrl
OAuth token endpoint
https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token
https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token
clientId
OAuth client identifier assigned to you
your-sandbox-client-id
your-prod-client-id
clientSecret
OAuth client secret
••••••••
••••••••
password
When using password grant
••••••••
••••••••
scope
Optional scope string
openid profile email
openid profile email
access_token
Bearer token stored after authentication
set by you
set by you
merchantId
Helpful for location and terminal examples
mer_4e5a13aa
mer_4e5a13aa
partnerId
Helpful for partner scoped examples
par_12345678
par_12345678
Credential profiles
Many teams use separate credentials for Boarding and for Payments. Create one Postman environment per credential set, or duplicate the environment and change clientId, clientSecret, and user credentials accordingly.
How to fetch a token
Use your preferred grant type. The example below shows a password grant. Client credentials grant follows the same token URL with grant_type=client_credentials.
curl -X POST "{{tokenUrl}}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id={{clientId}}" \
-d "client_secret={{clientSecret}}" \
-d "username={{username}}" \
-d "password={{password}}" \
-d "scope={{scope}}"Copy the access_token value into your Postman environment variable named access_token.
Example request using variables
curl -X GET "{{baseUrl}}/health" \
-H "Authorization: Bearer {{access_token}}"Versioning and updates
Spec version
OpenAPI v1 is the current public specification
Backward compatibility
Breaking changes are announced on the Changelog and communicated to registered partners
Regeneration
If your code generator requires a local file, re download the OpenAPI file when you see a new date on the Changelog
Troubleshooting
401 on every request
Missing or expired token
Refresh the token and confirm the Authorization header reads Bearer {{access_token}}
403 on valid token
Token from the other environment or missing permission
Confirm you used the correct environment and credentials for the endpoint
404 on known endpoint
Wrong base URL
Confirm baseUrl points to the correct environment
Request timeouts
Local firewall or VPN rules
Allow outbound traffic to the base URL and the identity host
Next steps
Review Authentication and OAuth
Reference Guide
Import the Location Management examples
Entity Management section
Set up webhook receivers
Webhook Event Reference
Last updated