Create Api Keys

Create API Key

POST /v1/keys/api

Mint a fresh API key for the calling user. The full secret value is included in the response and is not retrievable later — store it securely the moment you receive it. Subsequent calls to /keys/api only return a masked version (et_sk_a1b2...f6e7).

Account scope & permissions: the new key belongs to your active account. It authenticates as you, so it inherits your current role's permissions in that account — resolved live on every request. A key can never do more than your role allows, and if your role is changed the key's effective access changes with it. Use switch account to create a key scoped to a different account.

Revoked with membership: a key created by an account member is tied to that member. If you are removed from (or leave) the account, your keys for that account stop working immediately — requests return 401 — and the keys are deleted, even if never manually revoked. An account owner/admin (with settings permission) can also revoke any key bound to the account.

Keys can be scoped down with two optional fields: expires_in_days sets a hard expiry, and allowed_ips restricts which source IPs the key can authenticate from. Both are recommended for keys used by automation that runs from a known network.

Don't confuse this with POST /v1/auth/token (same effect, no body, hardcoded description) or POST /v1/keys/auth (which mints agent auth tokens, a different credential class).

Request body

description string

Free-form label. Pick something that identifies the key's purpose ("ci-bot", "production-deploy"). Shown in the dashboard and the list response.

expires_in_days int

Optional. Days until the key auto-expires. Omit for non-expiring keys. Recommended: rotate monthly for keys used by automation.

allowed_ips string

Optional comma-separated CIDR list ("10.0.0.0/8,192.168.1.0/24"). Requests using this key from outside these ranges are rejected with 401. Empty = no IP restriction.

Response (200 OK)

id int64

Numeric ID of the new key. Use in DELETE /v1/keys/api/{id}.

key string

The full secret. Shown once. Format: et_sk_ + base32 chars. Use this value in X-API-KEY headers.

Errors

400 Bad Request

Unknown body fields (handler uses strict decoding) or invalid JSON.

401 Unauthorized

Missing auth.

500

Crypto or database error generating the key. Safe to retry.

Request
curl -X POST "https://api.ngris.com/v1/keys/api" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "ci-bot",
    "expires_in_days": 90,
    "allowed_ips": "10.0.0.0/8"
  }'

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
key = client.api_keys.create_api_key(description="ci-bot")
print(key["key"])  # store this — only shown once

Response — 200 OK
{
  "id": 42,
  "key": "et_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

PreviousList API Keys NextDelete API Key

On this page

Create API Key