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

# Authentication

> API keys, agent keys, OAuth, and Bearer authentication

The Natural API uses Bearer authentication per [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). Include your credential in the `Authorization` header of every request:

```bash theme={null}
curl https://api.natural.co/payments \
  -H "Authorization: Bearer sk_ntl_prod_abc123..."
```

The same credential authenticates the [SDKs](/guides/platform/sdks), the [CLI](/guides/platform/cli), and REST calls. For AI hosts operating Natural through the [MCP connector](/guides/platform/mcp), use browser OAuth by default. API keys and agent keys remain available there only for CI, non-interactive, or non-OAuth fallback paths.

## Credential modes

Natural supports four credential modes. They differ in **who the request acts as** and **how agent identity is established**:

| Mode                                           | Prefix / flow         | Acts as                         |
| ---------------------------------------------- | --------------------- | ------------------------------- |
| [API key](#api-keys)                           | `sk_ntl_…`            | Your party                      |
| [Agent key](#agent-keys)                       | `ak_ntl_…`            | One specific agent, verified    |
| [User-scoped MCP OAuth](/guides/platform/mcp)  | Browser OAuth consent | The authorizing user            |
| [Agent-scoped MCP OAuth](/guides/platform/mcp) | Browser OAuth consent | Selected or new agent, verified |

Rules that follow from the table:

* **Bound credentials carry verified agent identity.** With an agent key or an agent-scoped OAuth grant, the server resolves the agent from the credential itself.
* **User-scoped money movement is valid.** Dashboard users, user-scoped MCP grants, and party API keys can move money as user/party actions without any agent attribution.
* **Agent-attributed money movement requires `X-Instance-ID`.** See [instance attribution](#instance-attribution-for-agent-money-movement).

Existing integrations that still claim agent attribution from a party API key can continue using the agent attribution header for now. Prefer agent keys or agent-scoped OAuth for new agent integrations.

## API keys

API keys are party-scoped credentials in the format `sk_ntl_{environment}_{secret}`:

| Prefix         | Environment |
| -------------- | ----------- |
| `sk_ntl_prod_` | Production  |

The production base URL is `https://api.natural.co`.

An API key acts as your party. For new agent integrations, use an agent key or agent-scoped OAuth instead of party-key attribution.

### Creating API keys

Create API keys from the [Natural Dashboard](https://natural.co/login) or via [`POST /api-keys`](/api-reference) after completing verification. The key secret is shown once — store it immediately.

Each key can be scoped to a subset of permissions. Scope a key down to exactly what the integration needs — for example, a read-only key, or one limited to payments:

```json theme={null}
{
  "data": {
    "attributes": {
      "name": "Carrier Payment Agent",
      "scopes": ["agents.read", "payments.create", "payments.read"]
    }
  }
}
```

## Agent keys

Agent keys are credentials bound to exactly one of your [agents](/guides/concepts/agents), in the format `ak_ntl_{environment}_{secret}`. Requests authenticated with an agent key resolve as that agent, verified by the credential itself.

```bash theme={null}
# Acts as the bound agent
curl https://api.natural.co/whoami \
  -H "Authorization: Bearer ak_ntl_prod_abc123..."
```

Agent keys work everywhere API keys work: SDKs, CLI, MCP fallback, and REST, including the standard short-lived token exchange the SDKs perform automatically.

### Creating agent keys

Create agent keys from the dashboard or via [`POST /agent-keys`](/api-reference), naming the existing agent it is bound to:

```json theme={null}
{
  "data": {
    "attributes": {},
    "relationships": {
      "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }
    }
  }
}
```

The create response includes the full secret in `attributes.agentKey` exactly once. List and revoke responses only include the non-secret `agentKeyPrefix`.

### Agent key permissions

Agent keys do not take user-selected scopes. They always receive Natural's server-defined agent credential policy: broad operational capability for the bound agent (payments, payment requests, transfers, wallet reads, customer reads) with hard exclusions that no agent credential can ever hold:

* Creating agents
* Creating, listing, or revoking API keys or agent keys
* Team membership and account control
* Party profile/admin changes
* Wallet lifecycle/admin operations
* Vault funds

Agent-scoped MCP OAuth grants are clamped by the same policy.

### Rotation

Rotation is overlapping, never atomic: create a replacement key, deploy it, then revoke the old key. Multiple active keys per agent are valid, so a running deployment never loses access mid-rotation. Revoking a key stops it immediately for raw-key requests and new token exchanges; short-lived tokens already minted from it expire within their 15-minute TTL.

## Instance attribution for agent money movement

Agent-attributed money movement (payments, transfers, payment-request fulfillment) always requires an `X-Instance-ID` header — a caller-chosen run/session/conversation identifier that answers "which run of the agent did this". This applies to agent keys, agent-scoped OAuth grants, and legacy party-key attribution. Reads do not require it.

A money-movement request from an agent-bound credential without `X-Instance-ID` is rejected with `400 missing_instance_id`:

```bash theme={null}
curl -X POST https://api.natural.co/payments \
  -H "Authorization: Bearer ak_ntl_prod_abc123..." \
  -H "X-Instance-ID: invoice-run-1234" \
  -H "Idempotency-Key: pay-invoice-1234" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": { ... } } }'
```

SDK equivalent — when authenticating with an agent key, the instance ID is required on money-movement methods (and no agent ID is passed):

```python theme={null}
from naturalpay import Natural

client = Natural()  # NATURAL_API_KEY=ak_ntl_prod_...

payment = client.payments.create(
    amount=10000,
    currency="USD",
    counterparty={"type": "email", "value": "contractor@example.com"},
    description="Invoice #1234",
    x_instance_id="invoice-run-1234",  # required for money movement with an agent key
    idempotency_key="pay-invoice-1234",
)
```

User-scoped requests (dashboard, user-scoped MCP, and plain API key calls) are not agent-attributed and do not need `X-Instance-ID`.

## MCP OAuth

The [MCP connector](/guides/platform/mcp) authenticates AI hosts with browser OAuth. During consent you choose the grant subject:

* **As me (user-scoped)** — tool calls act as you, with your party permissions. This is the default, and existing grants stay user-scoped until you reconnect and choose otherwise.
* **As an agent (agent-scoped)** — choose **New agent** to create an agent during OAuth approval, or select one of your existing agents. Tool calls act as that agent with the clamped agent credential policy. Agent-scoped grants cannot create agents or manage keys after authorization.

Agent-scoped grants already carry the selected or newly created agent identity. User-scoped grants act as user/party actions.

## Checking your identity

`GET /whoami` returns the resolved subject for any credential: actor type, party, agent ID and how it was established (`credential`, `oauth_grant`, or `header`), credential kind, and key/grant IDs. Use it to verify which mode a credential resolves to.

## Security

* Store keys in a dedicated secret management system. Never commit them to source control. Both `sk_ntl_` and `ak_ntl_` prefixes should be treated as secrets by your scanners.
* Rotate keys periodically. You can have multiple active keys to enable zero-downtime rotation.
* Revoke compromised keys immediately via the dashboard, `DELETE /api-keys/{keyId}`, or `DELETE /agent-keys/{keyId}`.
* All requests require HTTPS.

## Related

* [Agents](/guides/concepts/agents) — The agent model, instances, and audit trail
* [MCP](/guides/platform/mcp) — Connect Claude, Cursor, and other AI hosts to Natural
* [API Reference](/api-reference/about) — Create, list, and revoke keys
* [Error Handling](/api-reference/errors/error-handling) — Authentication error codes