Skip to main content
The Natural API uses Bearer authentication. Include your credential in the Authorization header of every request:
The same credential authenticates the SDKs, the CLI, and REST calls. AI hosts using the MCP connector authenticate with browser OAuth by default.

​
Credential modes

Natural supports four credential modes. They differ in who the request acts as and how agent identity is established: Key rules:
  • Bound credentials carry verified agent identity. With an agent key or agent-scoped OAuth grant, the server resolves the agent from the credential itself. This is the only way to act as an agent: a party API key or user credential plus an X-Agent-ID header is rejected with 403 agent_credential_required.
  • User-scoped money movement is valid. Dashboard users, user-scoped MCP grants, and party API keys can move money without any agent attribution.
  • Agent-attributed money movement requires X-Instance-ID. See instance attribution.

​
API keys

API keys are party-scoped credentials in the format sk_ntl_{environment}_{secret}: The production base URL is https://api.natural.com. An API key acts as your party and cannot act as an agent. To act as an agent, authenticate with an agent key or an agent-scoped OAuth grant.

​
Creating API keys

Create API keys from the Natural Dashboard or via POST /api-keys. 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:

​
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.
Agent keys work everywhere API keys work: SDKs, CLI, MCP fallback, and REST.

​
Creating agent keys

Create agent keys from the dashboard or via POST /agent-keys, naming the existing agent it is bound to:
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

POST /agent-keys/{keyId}/rotate issues a replacement while the old key stays valid for a grace period you choose, up to 24 hours. Multiple active keys per agent are valid, so a running deployment never loses access mid-rotation.

​
Instance attribution for agent money movement

Agent-attributed money movement (payments, transfers, payment-request fulfillment) requires an X-Instance-ID header — a caller-chosen identifier for the agent run making the call. Without it, the request is rejected with 400 missing_instance_id. Reads don’t require it, and user-scoped requests (dashboard, user-scoped MCP, and plain API keys) are never agent-attributed. In the SDKs, pass the instance ID when constructing the client; it is sent as X-Instance-ID on every request:

​
MCP OAuth

The MCP connector signs AI hosts in with browser OAuth. On the consent screen, you pick who the connection acts as:
  • As an agent (agent-scoped) — The default. Pick an existing agent or create a new one during approval. Tool calls then run as that agent, with the agent’s clamped permissions, and can’t create agents or manage keys.
  • As me (user-scoped) — Tool calls run as you, with your party’s permissions. You get this when you approve without picking an agent.
To switch modes, reconnect and choose again.

​
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 keys — Create, list, and revoke keys
  • Error Handling — Authentication error codes