API Keys

Programmatic tokens (nat_sk_…) scoped to a project or account.

Overview

Keys are created and scoped through the API (or app) to a project — the default — or the whole account, plus a set of capabilities. The raw secret is returned exactly once, at creation (or rotation); every other read returns only key_prefix. A project-scoped key cannot create a project or add a member, which is why Create a provider and Invite a colleague start from an account-wide one.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → API Keys.

Data Model

ApiKeyRecord

Field	Type	Description
id	string	Public API key ID.
name	string	Human-readable label.
key_prefix	string	The first characters of the secret, for identification without exposing it.
scope	string	project or account.
project_id	string, nullable	Set when scope is project — see Projects.
capabilities	string[]	The actions/resources this key is allowed to call.
created_at	string (date-time)
last_used_at	string (date-time), nullable

Key Concepts

The secret is write-only

ApiKeyCreated (the create/rotate response) is the only shape that includes the raw secret (nat_sk_…); it is never returned again. Losing it means rotating the key.

Rotation

POST /v1/api-keys/{api_key_id}:rotate issues a new secret for the same key record and invalidates the old one immediately.

A connected app cannot mint one

Creation and rotation are refused for an OAuth access token and for an Assistant turn, with 403 access_denied. Both credentials are re-read on every request so that disconnecting an app, or revoking a link, stops it immediately — and a nat_sk_… key minted beforehand would keep working afterwards, which is the one thing that immediacy exists to prevent.

Reading and revoking keys stay available to a connected app: both narrow what exists rather than widening it. Minting a key is a human act, or an act of a credential whose own authority hangs off no grant.

Deleting a project revokes its keys

DELETE /v1/projects/{project_id} revokes every key scoped to that project as part of the same operation. A revoked key stops authenticating immediately and every call with it returns 401 unauthorized — a clear signal that the credential's project is gone, rather than a 404 that reads like a wrong or mistyped id. There is no recovery for a project-scoped key once its project is deleted: mint a new key against a different project instead.

Examples

CLI

naturali create-api-key --name ci-deploy --project-id proj_V1StGXR8Z5jdHi6B

SDK

const { data: created } = await naturali.apiKeys.createApiKey({
  body: { name: 'ci-deploy', project_id: 'proj_V1StGXR8Z5jdHi6B' },
});
// created.key is the raw nat_sk_… secret, returned exactly once — store it now.

curl

curl -X POST https://api.naturali.ai/v1/api-keys \
  -H "Authorization: Bearer $NATURALI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-deploy", "project_id": "proj_V1StGXR8Z5jdHi6B" }'