Authentication
Every request carries one header, whatever the credential behind it:
Authorization: Bearer <credential>
The API tells the credentials apart by their shape, so there is nothing else to declare.
Credential types
| Credential | Who holds it | How to get one | Lifetime |
|---|---|---|---|
API key (nat_sk_…) | Your backend, CI, a script | POST /v1/api-keys while signed in — see API Keys | Until rotated or revoked |
| Session token (JWT) | A person in the app or the CLI | Sign in with a code emailed to the address — see Auth | 15 minutes; refresh for 30 days |
| OAuth access token (JWT) | An MCP client such as Claude or Cursor | The client runs OAuth 2.1 and you approve it — see MCP Server | 1 hour; the client refreshes for 30 days |
Use an API key for anything that runs without a person in front of it, and scope it to one project unless it genuinely needs the whole account. A session token is what the app holds; never store one where an API key would do. An OAuth token is minted for and held by the client that asked for it — you never copy it anywhere.
The raw nat_sk_… secret is returned once, at creation or rotation. A key
cannot be minted by an OAuth token: creating one is a human act.
What a credential reaches
A request acts in the project named in its path, /v1/projects/{project_id}/….
Two independent checks decide whether it may:
- Credential scope. A project-scoped API key reaches its one project. An OAuth token reaches the projects chosen on its consent screen. An account-scoped key and a session token reach every project the user belongs to.
- Membership. The user behind the credential must be a member of that
project, with a role wide enough for the action.
memberreads and writes every resource in the project;adminalso manages who is in it and how it is configured;owneralso deletes it. See Projects → Membership.
Scope narrows membership; it never widens it. A project-scoped key whose user is removed from the project stops reaching it.
Credentials are resolved on every request, not trusted from what a token claims. Revoking a key, disconnecting an app or changing a member's role takes effect on the next call, not when a token expires.
Who can do what
Every caller acts within a bound, which also holds on what the call causes: the
builtin and naturali actions of a generation it starts, and the records the
API reads on its behalf. A call outside it answers 403; an action outside it
inside a generation is a tool error the model reads.
| Caller | Acts within |
|---|---|
A session token, an OAuth token, an API key without capabilities | What the user's role reaches in the project |
An API key with capabilities | The operations it names (Capabilities narrow a key) |
| An MCP server's caller | tools:CallTool on the server's tools, plus the operation each builtin item runs on the resources it pins |
| A channel contact | Running the channel's agent in its conversation, or once for a oneshot |
| An Assistant grant | Reads only, unless its scopes include manage; with manage, what the account reaches |
| A trigger firing | The policies its policy_ids names |
A builtin tool | Its actions, within the bound of the call that ran it |
An agent acts for whoever started its turn. With run_as: caller (the
default) a turn acts within the caller's bound, capped by the agent's
policy_ids; with run_as: agent it acts within policy_ids alone
(Execution identity). An agent
behind an MCP server or a channel, whose caller holds only the server's tools
or the agent's turn, needs run_as: agent to take actions of its own, such as
a builtin tool call. To limit an agent whoever calls it, see
Limit what an agent may do.
When a request is refused
| Status | code | Means |
|---|---|---|
401 | UNAUTHORIZED | No Authorization header, a malformed one, or a credential that is unknown, expired or revoked. Refresh a session; replace a key. |
404 | RESOURCE_NOT_FOUND | The user is not a member of the project. A project you cannot reach looks the same as one that does not exist. |
403 | FORBIDDEN | The credential's scope excludes the project, or the role is too narrow — the message names the role the action needs. |
401 is about the credential and 403 about what it may do. Sign-in endpoints
also answer 429; see Rate limits.
Check which account a credential resolves to
GET /v1/users/me answers for every
credential type, which makes it the first call to try with a new one.
- CLI
- SDK
- curl
export NATURALI_TOKEN=nat_sk_...
naturali get-current-user
import { NaturaliClient } from '@naturali/sdk';
const naturali = new NaturaliClient({ token: process.env.NATURALI_TOKEN });
const { data: me } = await naturali.users.getCurrentUser();
curl https://api.naturali.ai/v1/users/me \
-H "Authorization: Bearer $NATURALI_TOKEN"