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

# auth.md

> How an AI agent authenticates with Atum APIs — no OAuth, no API keys, no registration endpoint.

You are an agent. Atum's hosted APIs do not use OAuth, OpenID Connect, or API keys. There is no agent registration endpoint and no access token to mint. A payment authorizes itself. Read this file, then follow the linked owner pages — do not invent an OAuth or signup flow.

## Audience

This file is for software that calls Atum's public REST APIs: the [Payment Gateway](https://docs.atum.xyz/api-reference/payment-gateway/introduction.md), the [x402 Facilitator](https://docs.atum.xyz/api-reference/x402/introduction.md), and [Veri-Fill](https://docs.atum.xyz/api-reference/veri-fill/introduction.md). Humans integrating the same APIs should start at [API Reference](https://docs.atum.xyz/api-reference/overview.md).

## Discover

Do not look for `/.well-known/openid-configuration`, `/.well-known/oauth-authorization-server`, or `/.well-known/oauth-protected-resource` on this host. Those documents are for OAuth-protected APIs. Atum's hosted APIs are not OAuth-protected.

Use these documents instead:

| What you need | Where it is |
| - | - |
| How to authenticate | This file, and [API Reference](https://docs.atum.xyz/api-reference/overview.md#authentication) |
| API catalog | [/.well-known/api-catalog.json](https://docs.atum.xyz/.well-known/api-catalog.json) |
| Capability manifest | [/.well-known/ai-catalog.json](https://docs.atum.xyz/.well-known/ai-catalog.json) |
| Base URLs | [Endpoints](https://docs.atum.xyz/get-started/reference/endpoints.md) |
| OpenAPI | [Payment Gateway](https://docs.atum.xyz/api-reference/payment-gateway/openapi.yaml), [x402 Facilitator](https://docs.atum.xyz/api-reference/x402/openapi.yaml) |
| Docs MCP | [https://docs.atum.xyz/mcp](https://docs.atum.xyz/mcp) |

## How a call is authorized

There is no API key, bearer token, or authorization header on any Payment Gateway, x402 Facilitator, or Veri-Fill operation. Veri-Fill needs no credentials either; see [Veri-Fill API](https://docs.atum.xyz/api-reference/veri-fill/introduction.md).

* **Writes that move funds:** `POST /v1/payments` carries a `sender_auth` signature that proves control of the funding account — build and sign it with the [SDK or CLI](https://docs.atum.xyz/get-started/start-building/build-with-the-sdk.md); do not hand-roll the signature. x402 `/settle` is called by the [resource server](https://docs.atum.xyz/get-started/reference/glossary.md#resource-server) with the payer's signed credential; that credential's `paymentRequest` includes `sender_auth`. See [x402 Facilitator](https://docs.atum.xyz/api-reference/x402/introduction.md).
* **Reads** (`/status`, `/resolve`, `/timeline`, `/v1/defaults`, x402 `/supported`, Veri-Fill) need no credentials.
* **Quote requests** are not signed. Spend authorization is deferred to award time. See [Get a price quote](https://docs.atum.xyz/get-started/get-a-price-first.md).

Full field shapes are on the endpoint pages. The convention those APIs share is on [API Reference](https://docs.atum.xyz/api-reference/overview.md).

## Identity is not a login

[Atum ID](https://docs.atum.xyz/get-started/identity/overview.md) is a signed fact attached to a payment or quote. It is not a username, not a session, and not permission to move funds. You can submit and settle without credentials. If you attach them, Atum verifies them.

[Know Your Agent](https://docs.atum.xyz/get-started/identity/know-your-agent.md) is the separate question of who is answerable when software spends. Two signed grants (principal delegation + Atum recognition) are how that works. They are not a self-serve integration: there is no public `POST /agent/identity`, `POST /agent/auth`, or `POST /oauth2/token` on Atum.

Today, an agent that calls Atum either:

1. **Holds the signing key** — the agent signs `sender_auth` and submits, the same way the CLI and examples do. Treat that key as a production signer.
2. **Acts for a principal** — the agent assembles the request; the principal's signer completes it. Prepare-only.

See [Agentic payouts](https://docs.atum.xyz/get-started/use-cases/agentic-payouts.md#who-signs).

## Supported methods

| Method | Supported | What to do |
| - | - | - |
| `sender_auth` on a signed payment | Yes | Build and sign with the SDK or CLI, then `POST` to `https://payment-gw.production-testnet.atum.xyz/v1/payments` (testnet) or `https://payment-gw.production-mainnet.atum.xyz/v1/payments` (mainnet) |
| Unauthenticated reads | Yes | Call the read path with no `Authorization` header |
| OAuth 2.0 / OIDC | No | Do not start an authorization-code, client-credentials, or JWT-bearer grant |
| API key | No | Do not send `x-api-key` or a bearer token |
| Agent registration (auth.md OAuth profile) | No | Do not `POST /agent/auth` or `POST /agent/identity` |

## What to call

1. Confirm the gateway is reachable: `GET https://payment-gw.production-testnet.atum.xyz/v1/defaults` (testnet) or `GET https://payment-gw.production-mainnet.atum.xyz/v1/defaults` (mainnet). See [Endpoints](https://docs.atum.xyz/get-started/reference/endpoints.md).
2. Build and sign a payment with the [SDK or CLI](https://docs.atum.xyz/get-started/start-building/build-with-the-sdk.md).
3. Submit to [`POST /v1/payments`](https://docs.atum.xyz/api-reference/payment-gateway/submit-payment). Reuse the same `request_id` if you retry — see [Idempotency](https://docs.atum.xyz/api-reference/idempotency.md).
4. If you are paying for or gating an HTTP resource, use [Facilitated payments (x402)](https://docs.atum.xyz/payment-protocols/x402/overview.md) or [Direct payments (MPP)](https://docs.atum.xyz/payment-protocols/mpp/overview.md).

## Next steps

> [card] [API Reference](https://docs.atum.xyz/api-reference/overview.md)
>
> Shared conventions for the hosted REST APIs

> [card] [Endpoints](https://docs.atum.xyz/get-started/reference/endpoints.md)
>
> Testnet and mainnet base URLs

> [card] [Know Your Agent](https://docs.atum.xyz/get-started/identity/know-your-agent.md)
>
> Who is answerable when software spends

> [card] [SDK quickstart](https://docs.atum.xyz/get-started/start-building/build-with-the-sdk.md)
>
> Build and sign a payment


## Related topics

- [API Reference](https://docs.atum.xyz/api-reference/overview.md)
- [Error codes](https://docs.atum.xyz/errors.md)
- [Submit payment request](https://docs.atum.xyz/api-reference/payment-gateway/submit-payment.md)
- [Atum infrastructure](https://docs.atum.xyz/get-started/architecture/payment-rails-primer.md)
- [Glossary](https://docs.atum.xyz/get-started/reference/glossary.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.