Create Key | Captain

import json
import requests
BASE_URL = "https://acme.captain.dev"
API_KEY = "your_write_key"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
response = requests.post(
    f"{BASE_URL}/v1/keys",
    headers=headers,
    json={
        "type": "search",
        "indexes": ["products-staging"],
        "description": "staging storefront",
    },
    timeout=30.0,
)
print(json.dumps(response.json(), indent=2))

{
  "id": "key_8a1f3c0d9e2b4f67",
  "type": "search",
  "prefix": "cap_k3Jd9x",
  "indexes": [
    "products-staging"
  ],
  "description": "staging storefront",
  "created_at": 1759433001,
  "key": "cap_k3Jd9xEXAMPLEONLY",
  "created_by": "key_2c7e90a1b4d35f18",
  "note": "store this key now: it is shown once and kept only as a hash"
}

Mint a key. A write key for every index mints search, scoped, write and issuer keys. An issuer key mints scoped keys only, for its own indexes, with an expires_at within its max_ttl, and its own filter added. Any other key gets 403. The secret is in this reply only.

Authentication

AuthorizationBearer

A write key, issued by Captain. Server side only. Sent as Authorization: Bearer <key>.

AuthorizationBearer

An issuer key, issued by Captain. Server side only. It only mints scoped keys. Sent as Authorization: Bearer <key>.

Request

This endpoint expects an object.

indexeslist of stringsRequired

index names, or [”*”] for every index, now and later. A scoped key names its indexes

typeenumOptionalDefaults to search

search (default): search, typeahead, browse, similar, Get Records, events and analytics on its indexes. scoped: search, typeahead, browse, similar, Get Records and events on its indexes, with an optional filter added to every query and usually an expiry; no analytics. issuer: a server-side key that only mints scoped keys within its indexes, filter and max_ttl; it cannot search, and revoking it revokes every key it minted. write: a server-side key for its indexes: add, update and delete records, change settings (all but acl, tenant_field and audit), synonyms, rules and aliases, list and delete indexes, import from Algolia, and read jobs and usage. It cannot search or read analytics. A write key for every index ([”*”]) also creates and copies indexes, and creates, lists and revokes keys. console: Captain’s own; a write key that asks for one gets 400. An issuer key may only ask for scoped.

Allowed values:

principalslist of stringsOptional

scoped keys only: the users, groups or roles this key acts for (record access control)

filter_exprstringOptional

scoped keys only: a filter expression ANDed into every query

max_ttlintegerOptional60-86400Defaults to 3600

issuer keys: the longest expiry it may give

filterobjectOptional

scoped keys only: ANDed into every query; a request can narrow it, never widen it. Same syntax as the search filters. Query understanding (typo correction, completion) learns only from the records it matches.

expires_atintegerOptional

unix seconds

allowed_originslist of stringsOptional

browser origins allowed to use the key; empty = any

descriptionstringOptional<=200 characters

rate_limitdoubleOptionalDeprecated

accepted and ignored: no key is rate limited

Response

created; the key is in this response only

idstringOptional

typeenumOptional

Allowed values:

prefixstringOptional

operatorstringOptional

minted by a console key: the person it was minted for, fixed. Its events record it, and a request with it may not send X-Captain-Operator

principalslist of stringsOptional

filter_exprstringOptional

max_ttlintegerOptional

issued_bystringOptional

issued_by_captainbooleanOptional

in a write key’s view: a key Captain issued (a console or support key). Its operator and description are left out, and only Captain revokes it

indexeslist of stringsOptional

filterobject or nullOptional

expires_atinteger or nullOptional

allowed_originslist of stringsOptional

descriptionstringOptional

created_atintegerOptional

keystringOptional

only in the response to POST /v1/keys