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

# Organization Access Tokens

> Long-lived server-side tokens for scripts, agents, and backend integrations — scoped, expiring, and tied to one organization.

Organization Access Tokens (OATs) are the simplest way to call the Macropay API from your own backend. Where [OAuth2](/integrate/oauth2/introduction) is built for apps acting on behalf of *other* organizations, an OAT acts on behalf of **your** organization only — perfect for cron jobs, internal services, deploy scripts, and AI agents that need to talk to your account directly.

<Info>
  An OAT is a bearer credential. Treat it like a password: store it in a secret manager or environment variable, never commit it to source control, and never ship it in client-side or browser code.
</Info>

## When to use an OAT

| You want to...                                                        | Use                                      |
| --------------------------------------------------------------------- | ---------------------------------------- |
| Run a backend service or script against your own org                  | **OAT**                                  |
| Bill agent activity to your org via the [Signals API](/api-reference) | **OAT**                                  |
| Let a third-party app act for *many* organizations                    | [OAuth2](/integrate/oauth2/introduction) |
| Authenticate end customers into the portal                            | Customer sessions                        |

Because the token is bound to a single organization, there's no consent screen and no token-refresh dance — you mint it once, grant exactly the scopes you need, and use it as a `Bearer` token until it expires.

## Create a token

<Steps>
  <Step title="Open organization settings">
    In the [Macropay dashboard](https://app.macropay.ai) sidebar, go to **Settings** > **General**. You can also jump straight there:

    `https://macropay.ai/dashboard/${org_slug}/settings`

    <img height="200" src="https://mintcdn.com/macrodeepinc/Uu6hOe0dMZnKqgkh/assets/integrate/authentication/settings.png?fit=max&auto=format&n=Uu6hOe0dMZnKqgkh&q=85&s=3775a8670513e7e43ea5fe9d6cf02354" data-path="assets/integrate/authentication/settings.png" />
  </Step>

  <Step title="Open the Developers section">
    Scroll to **Developers** and click **New Token**.
  </Step>

  <Step title="Configure the token">
    * **Name** — something descriptive (e.g. `billing-cron-prod` or `support-agent`) so you can identify and revoke it later.
    * **Expiration** — pick the shortest lifetime that fits the job. Short-lived tokens limit the blast radius if one ever leaks.
    * **Scopes** — grant only the permissions this token actually needs. A metering script that ingests events shouldn't be able to issue refunds.

    <img height="200" src="https://mintcdn.com/macrodeepinc/Uu6hOe0dMZnKqgkh/assets/integrate/authentication/oat-configuration.png?fit=max&auto=format&n=Uu6hOe0dMZnKqgkh&q=85&s=491730f00e5ab8c64049e08306440554" data-path="assets/integrate/authentication/oat-configuration.png" />
  </Step>
</Steps>

<Warning>
  The token value is shown **once**, at creation time. Copy it immediately into your secret store — you can't retrieve it again, only revoke it and issue a new one.
</Warning>

## Use the token

Send the token in the `Authorization` header as a bearer credential against the API base `https://api.macropay.ai`.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.macropay.ai/v1/products \
    -H "Authorization: Bearer $MACROPAY_OAT"
  ```

  ```ts TypeScript theme={null}
  import { Macropay } from "@macropay/sdk";

  const macropay = new Macropay({
    accessToken: process.env.MACROPAY_OAT,
  });

  const products = await macropay.products.list();
  ```

  ```python Python theme={null}
  import os
  from macropay import Macropay

  macropay = Macropay(access_token=os.environ["MACROPAY_OAT"])

  products = macropay.products.list()
  ```
</CodeGroup>

### Example: bill an agent's activity

A common backend use of an OAT is reporting agent work to the [Signals API](/api-reference) so it can be metered and turned into a value receipt. Scope the token to signal ingestion and nothing else:

```bash theme={null}
curl https://api.macropay.ai/v1/signals \
  -H "Authorization: Bearer $MACROPAY_OAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_support_triage",
    "customer_id": "cus_8Qz1",
    "type": "outcome",
    "name": "ticket_resolved",
    "value": 1
  }'
```

Activity and outcome signals feed Macropay's usage-based billing and let you certify each agent's ROI without wiring up a separate metering pipeline.

## Security best practices

<AccordionGroup>
  <Accordion title="Scope tightly">
    Treat scopes as the access boundary. Issue separate tokens per service so a leaked metering token can't touch payouts or customer data.
  </Accordion>

  <Accordion title="Expire early, rotate often">
    Set a real expiration date and rotate tokens on a schedule. For one-off scripts, prefer a token that expires in days, not years.
  </Accordion>

  <Accordion title="Keep tokens server-side">
    Never embed an OAT in a frontend bundle, mobile app, or anything a customer can inspect. For browser-facing flows, use hosted checkout or OAuth2 instead.
  </Accordion>

  <Accordion title="Revoke on suspicion">
    Revoke immediately from **Settings > Developers** if a token may have been exposed. Revocation takes effect right away — no propagation delay.
  </Accordion>
</AccordionGroup>

<Tip>
  Build and test against the [sandbox environment](/integrate/sandbox) first. Sandbox tokens are isolated from production, so you can iterate on scopes and integration logic without touching live data or real payouts.
</Tip>