API Keys

Create an API key

Creates an API key. When project_id is set the key is scoped to that project (the default and recommended stance); omit it for an account-scoped key. capabilities narrows what the key may do; when omitted the key inherits the creator's capabilities. The raw key (nat_sk_…) is returned only in this response. A project-scoped key requires membership of that project. The key carries no role of its own — every request it makes resolves its holder's membership again — so it can never reach past what its minter already had. An account-scoped key requires a credential that is not itself confined to one project. A connected app cannot create keys at all: a grant is revocable and a key is not, so a key minted under a grant would still work after the app was disconnected. Reading and revoking keys stay available.

post/v1/api-keys

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/api-keys
  • Auth: HTTP bearer

Request body

namestring required

Key name for identification.

project_idstring

Project to scope the key to. Omit for an account-scoped key.

capabilitiesstring[]

Capabilities to grant. Omit to inherit the creator's capabilities.

Example request

{
  "name": "CI/CD Pipeline",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "capabilities": [
    "agents:read",
    "sessions:write"
  ]
}

Response

API key created. The raw key value is only returned here.

idstring required

Public API key ID (key_ prefix).

namestring required
key_prefixstring required

Leading characters of the raw key, for identification.

scope'project' | 'account' required

Whether the key is scoped to one project or the whole account.

project_idstring nullable

The project this key is scoped to; null for account-scoped keys.

capabilitiesstring[] required

Capabilities granted to this key. Empty means it inherits the creator's.

created_atstring date-time required
last_used_atstring date-time nullable

When the key was last presented; null if never used.

keystring required

The raw API key value (only returned once, at creation or rotation). Use as the Bearer token.

Example response

{
  "id": "key_V1StGXR8Z5jdHi6B",
  "name": "CI/CD Pipeline",
  "key_prefix": "nat_sk_a1b2c3",
  "scope": "project",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "capabilities": [
    "agents:read",
    "sessions:write"
  ],
  "created_at": "2026-07-17T00:00:00.000Z",
  "last_used_at": "2026-07-17T09:12:00.000Z",
  "key": "nat_sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

Changes

No recorded changes to this operation across all 1 revision of this API.