Skip to main content
The Natural API uses Bearer authentication per RFC 6750. Include your credential in the Authorization header of every request: 
curl https://api.natural.co/payments \
  -H "Authorization: Bearer sk_ntl_prod_abc123..."
The same credential authenticates the SDKs, the CLI, and REST calls. For AI hosts operating Natural through the MCP connector, 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:
ModePrefix / flowActs as
API keysk_ntl_…Your party
Agent keyak_ntl_…One specific agent, verified
User-scoped MCP OAuthBrowser OAuth consentThe authorizing user
Agent-scoped MCP OAuthBrowser OAuth consentSelected 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.
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}:
PrefixEnvironment
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 or via POST /api-keys 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: 
{
  "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, in the format ak_ntl_{environment}_{secret}. Requests authenticated with an agent key resolve as that agent, verified by the credential itself. 
# 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, naming the existing agent it is bound to: 
{
  "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: 
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): 
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 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.
  • Agents — The agent model, instances, and audit trail
  • MCP — Connect Claude, Cursor, and other AI hosts to Natural
  • API Reference — Create, list, and revoke keys
  • Error Handling — Authentication error codes