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

traffic_typeenumOptionalDefaults to real

search, scoped and issuer keys: test or sim makes every search and event sent with this key test or sim traffic, left out of analytics, revenue and usage by default (a key for load tests, QA or a shopper simulator). An issuer passes it to the keys it mints. Engine RC11.9.14 and later. RC11.9.12 doesn’t have it.

Allowed values:

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

traffic_typeenumOptional

present on a test or sim key. Engine RC11.9.14 and later. RC11.9.12 doesn't have it.

Allowed values:

created_atintegerOptional

keystringOptional

only in the response to POST /v1/keys