> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate Macropay API requests with organization access tokens or OAuth 2.0 — plus automatic leak protection.

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.

<Info>
  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.
</Info>

## Pick the right method

<CardGroup cols={2}>
  <Card title="Organization Access Tokens" icon="key" href="/integrate/oat">
    **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.
  </Card>

  <Card title="OAuth 2.0 Provider" icon="users" href="/integrate/oauth2/introduction">
    **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.
  </Card>
</CardGroup>

|                       | Organization Access Token                      | OAuth 2.0                             |
| --------------------- | ---------------------------------------------- | ------------------------------------- |
| **Acts on behalf of** | Your own organization                          | Another org that authorizes your app  |
| **Best for**          | Backends, scripts, AI agents, server-to-server | Marketplace and partner integrations  |
| **Setup**             | Created in organization settings               | App registration + authorization flow |

## 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:

```bash theme={null}
curl https://api.macropay.ai/v1/products \
  -H "Authorization: Bearer macropay_oat_..."
```

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](/integrate/oat) for the full walkthrough.

<Tip>
  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.
</Tip>

## OAuth 2.0 for partner integrations

Building an app that other Macropay merchants install? Use the [OAuth 2.0 provider](/integrate/oauth2/introduction). 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](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning). 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.

<Warning>
  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.
</Warning>

### 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](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) is the reference we recommend.