Skip to main content
Every call to the Macropay API is authenticated with a bearer token. Which kind of token you reach for depends on who is making the request: your own code acting on behalf of your organization, or a third-party app acting on behalf of someone else’s organization.
Treat every bearer token like a password. Keep it server-side, never commit it to a repo, and never expose it in client-side code, mobile bundles, or browser network requests.

​
Pick the right method

Organization Access Tokens

Recommended for your own integrations. A long-lived token scoped to a single organization. Generate it in seconds from your dashboard and start calling the API.

OAuth 2.0 Provider

For partner integrations. Let other Macropay organizations grant your app scoped access — the right choice when you build for tools like Zapier, Slack, or Raycast.

​
Organization Access Tokens

An organization access token (OAT) is bound to exactly one of your organizations. Create it from that organization’s settings, then send it as a bearer token on every request:
Because OATs work for any endpoint your organization can reach, they’re the simplest path for backend services, automation, and agent billing — for example, an AI agent that posts activity and outcome signals to POST /v1/signals so you can bill by usage or verified ROI. See the organization access token guide for the full walkthrough.
Scope by purpose, not by convenience. Issue a separate token per service or environment so you can rotate or revoke one without taking the others down.

​
OAuth 2.0 for partner integrations

Building an app that other Macropay merchants install? Use the OAuth 2.0 provider. Each organization explicitly authorizes your app, and you receive a token scoped to the permissions they grant — no merchant ever hands you their raw OAT.

​
Automatic leak protection

Macropay is the merchant of record for everything you sell, so protecting your account credentials is part of protecting your revenue. We continuously watch for tokens that surface in public places and revoke them before they can be abused. We participate in the GitHub Secret Scanning Program. The moment GitHub detects a Macropay token in a public repository, gist, or discussion, we’re notified and that token is revoked immediately — no action required on your part.
If you get an email saying one of your tokens leaked, the token is already dead. The message includes the token type and where it was found so you can swap in a replacement and trace how it escaped.

​
Keep tokens out of the open

A few habits prevent most leaks:
  • Load tokens from environment variables or a secrets manager — never inline them in source.
  • Add .env and credential files to .gitignore before your first commit.
  • Use distinct tokens per environment so a leaked sandbox key never touches production.
  • Rotate on a schedule and immediately after any teammate offboards.
For a deeper checklist, the OWASP Secrets Management Cheat Sheet is the reference we recommend.