API Keys

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

Overview

Keys are created and scoped through the API (or console) 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.

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.

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_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-deploy", "project_id": "proj_V1StGXR8Z5jdHi6B" }'