API keys

Create and revoke the keys your code uses.

List API keys #

GET /v1/api-keys app session

The signed-in user's active API keys (revoked ones are not listed).

More about this

Secrets are never returned.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

GET

curl "https://cirrus.pocketful.in/v1/api-keys" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/api-keys",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/api-keys', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": [
    {
      "key_id": "ck_8LLRuKYXrNrKH7sorU01",
      "name": "Trading bot",
      "scopes": [
        "read",
        "orders"
      ],
      "ip_allowlist": [
        "203.0.113.7"
      ],
      "created_at": "2026-09-29T12:02:21.670710+00:00",
      "last_used_at": null
    }
  ],
  "error": null
}

Create an API key #

POST /v1/api-keys app session

Creates a long-lived API key with the chosen scopes (and optionally an IP allowlist).

More about this

The secret is in this response only: store it now. Authenticate with Authorization: token <key_id>:<api_secret>. At most 10 keys may be active at once.

Only the account holder, signed in themselves, can create keys (an operator acting as the user gets 403 own_session_required).

Body fields

name string required

A label for the key, 1-64 characters (trimmed).
scopes string[] required

What the key may do; at least one.

One of: read, orders, triggers
ip_allowlist string[]

IP addresses (v4 or v6) the key may be used from, at most 20; empty or absent = any.

Errors

HTTP	Code	When
400	malformed_json	The body is not JSON, or does not fit the request shape (unknown or missing fields, wrong types).
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	own_session_required	Credentials can only be created from the user's own signed-in session.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

POST

curl -X POST "https://cirrus.pocketful.in/v1/api-keys" \
  -H "Authorization: token $CIRRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trading bot",
    "scopes": [
      "read",
      "orders"
    ],
    "ip_allowlist": [
      "203.0.113.7"
    ]
  }'

import os

import requests

response = requests.post(
    "https://cirrus.pocketful.in/v1/api-keys",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    json={
        "name": "Trading bot",
        "scopes": [
            "read",
            "orders",
        ],
        "ip_allowlist": [
            "203.0.113.7",
        ],
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/api-keys', {
  method: 'POST',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Trading bot",
    "scopes": [
      "read",
      "orders"
    ],
    "ip_allowlist": [
      "203.0.113.7"
    ]
  }),
});
const body = await response.json();
console.log(response.status, body);

Response · 201

{
  "status": "success",
  "data": {
    "key_id": "ck_8LLRuKYXrNrKH7sorU01",
    "name": "Trading bot",
    "scopes": [
      "read",
      "orders"
    ],
    "ip_allowlist": [
      "203.0.113.7"
    ],
    "created_at": "2026-09-29T12:02:21.670710+00:00",
    "last_used_at": null,
    "api_secret": "cs_tOAqnQNn6z1YyoyVTT4tePcHhjAPl3zmox41QEeb",
    "note": "Store the secret now: it is not shown again."
  },
  "error": null
}

Revoke an API key #

DELETE /v1/api-keys/{key_id} app session

Revokes the key at once: requests with it are refused from now on (on every server within a few seconds at most).

Parameters

key_id path · string required

The key's key_id (ck_...).

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	api_key_not_found	No API key with this id for the caller.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

DELETE

curl -X DELETE "https://cirrus.pocketful.in/v1/api-keys/<key_id>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.delete(
    "https://cirrus.pocketful.in/v1/api-keys/<key_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/api-keys/<key_id>', {
  method: 'DELETE',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "key_id": "ck_8LLRuKYXrNrKH7sorU01",
    "revoked": true
  },
  "error": null
}