API Keys

Torque uses API keys for authentication. The bootstrap key (set at startup) creates additional keys with specific actions, collection scopes, and expiration.

Authentication

All API requests require an API key, sent via the X-TYPESENSE-API-KEY header:

curl http://localhost:8108/collections \
  -H "X-TYPESENSE-API-KEY: YOUR_API_KEY"

Bootstrap Key

The bootstrap key is set when starting the server with --api-key. It has full access to all actions and collections. Use it to create more restricted keys for applications.

torque-server --api-key YOUR_BOOTSTRAP_KEY

Create an API Key

POST /keys
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_BOOTSTRAP_KEY

{
  "description": "Search-only key for products",
  "actions": ["documents:search"],
  "collections": ["products"]
}

The response includes the full key value. This is the only time the full key is shown — store it securely:

{
  "id": 1,
  "value": "abc123...",
  "key_prefix": "abc1",
  "description": "Search-only key for products",
  "actions": ["documents:search"],
  "collections": ["products"]
}

Available Actions

Action	Description
`documents:search`	Search documents across allowed collections
`collections:*`	Create, read, update, and delete collections
`documents:*`	Import, create, read, update, and delete documents
`keys:*`	Manage API keys
`synonyms:*`	Manage synonym sets
`presets:*`	Manage presets
`stopwords:*`	Manage stopword sets
`*`	Full access to all actions

Collection Scope

Restrict a key to specific collections:

{
  "description": "Products search key",
  "actions": ["documents:search"],
  "collections": ["products", "categories"]
}

An empty collections array grants access to all collections.

Key Expiration

Set an expiration timestamp (Unix seconds) and optionally auto-delete the key when it expires:

{
  "description": "Temporary key",
  "actions": ["documents:search"],
  "collections": ["products"],
  "expires_at": 1710000000,
  "autodelete": true
}

Scoped Search Keys (HMAC)

Generate client-side scoped keys that embed additional restrictions (collection, expiration) into an HMAC-signed token. Scoped keys are derived from a parent key and can only be validated by the server.

This allows you to create per-user search keys on your backend without making API calls to Torque for each user.

List API Keys

GET /keys
X-TYPESENSE-API-KEY: YOUR_BOOTSTRAP_KEY

Returns key metadata (ID, prefix, description, actions, collections). Full key values are not shown.

Get an API Key

GET /keys/1
X-TYPESENSE-API-KEY: YOUR_BOOTSTRAP_KEY

Delete an API Key

DELETE /keys/1
X-TYPESENSE-API-KEY: YOUR_BOOTSTRAP_KEY

Persistence

API keys are persisted to disk and restored on server restart.