Organization Access Tokens

Organization Access Tokens (OATs) are the simplest way to call the Macropay API from your own backend. Where OAuth2 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.

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.

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	OAT
Let a third-party app act for many organizations	OAuth2
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

Open organization settings

In the Macropay dashboard sidebar, go to Settings > General. You can also jump straight there:https://macropay.ai/dashboard/${org_slug}/settings

Open the Developers section

Scroll to Developers and click New Token.

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.

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.

Use the token

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

curl https://api.macropay.ai/v1/products \
  -H "Authorization: Bearer $MACROPAY_OAT"

import { Macropay } from "@macropay/sdk";

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

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

import os
from macropay import Macropay

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

products = macropay.products.list()

Example: bill an agent’s activity

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

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

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.

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.

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.

Revoke on suspicion

Revoke immediately from Settings > Developers if a token may have been exposed. Revocation takes effect right away — no propagation delay.

Build and test against the sandbox environment first. Sandbox tokens are isolated from production, so you can iterate on scopes and integration logic without touching live data or real payouts.

Bootup

Features

Integrate

Merchant of Record (MoR)

Organization Access Tokens

When to use an OAT

Create a token

Use the token

Example: bill an agent’s activity

Security best practices

​When to use an OAT

​Create a token

​Use the token

​Example: bill an agent’s activity

​Security best practices

When to use an OAT

Create a token

Use the token

Example: bill an agent’s activity

Security best practices