Skip to content

Cluster API Keys API ​

Every Typesense Cloud cluster has its own set of Typesense Server API keys, which your applications use to talk to the cluster directly.

There are three ways to create these keys:

You want toUse
Get an admin key and a search-only key for a new clusterGenerate API key
Create a key limited to certain actions, collections or an expiry date, or list and revoke keysThe endpoints on this page
Create and manage keys from your own applicationThe cluster's own /keys endpoint

The first two are part of the Cloud Management API, so they work with your account's management API key. That lets you manage the keys of any cluster in your account without holding each cluster's admin key, for example from a script that provisions clusters. The cluster's /keys endpoint is part of the Typesense Server API, so you call it on the cluster's hostname with the cluster's admin key.

All three create the same kind of key on the cluster. So you can list and revoke a key here, no matter how it was created.

The cluster has to be in_service for these endpoints.

List all API keys ​

This endpoint lists every API key on the cluster, newest first.

shell
curl -X GET --location "https://cloud.typesense.org/api/v1/clusters/<ClusterId>/api-keys" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

json
[
  {
    "id": 3,
    "description": "Storefront search",
    "actions": ["documents:search"],
    "collections": ["products"],
    "expires_at": 1792108800,
    "value_prefix": "y7CF"
  },
  {
    "id": 2,
    "description": "Search-only key",
    "actions": ["documents:search"],
    "collections": ["*"],
    "expires_at": 64723363199,
    "value_prefix": "kQ2n"
  },
  {
    "id": 1,
    "description": "Admin key",
    "actions": ["*"],
    "collections": ["*"],
    "expires_at": 64723363199,
    "value_prefix": "cBKq"
  }
]
FieldDescription
idThe key's id on the cluster. Use it to revoke the key.
descriptionWhat the key is for
actionsThe Typesense actions the key permits, for example documents:search. * permits every action.
collectionsThe collection names or regular expressions the key covers. * covers every collection.
expires_atWhen the key stops working, as a Unix timestamp in seconds. A key that never expires reports a far-future value.
value_prefixThe first characters of the key's value. The full value is never returned here.

To see when each key was last used, match value_prefix against the API key last use endpoint.

Keys Typesense Cloud creates for itself show up in the list too, for example the temporary key for a bulk import you start through the MCP Server.

Create an API key with a given scope ​

WARNING

You want to keep admin keys on your servers. Give applications a key limited to the actions and collections they need. When different users need to see different parts of one collection, use a scoped search key derived from a search-only key.

Here's how to create a search key for one collection that expires on a given date:

shell
curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterId>/api-keys/custom" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "description": "Storefront search",
          "actions": ["documents:search"],
          "collections": ["products"],
          "expires_at": 1792108800
        }'

Request Parameters ​

ParameterRequiredDescription
actionsRequiredArray of Typesense action names the key permits, for example ["documents:search"]. ["*"] creates an admin key.
collectionsRequiredArray of collection names or regular expressions the key covers, for example ["products"] or ["products_.*"]. ["*"] covers every collection.
descriptionOptionalWhat the key is for.
expires_atOptionalUnix timestamp in seconds after which the key stops working. Omit it for a key that never expires.

TIP

Typesense doesn't check action names, so a misspelled action never matches anything.

Response:

You'll get an HTTP 201 with the new key, including its value:

json
{
  "id": 3,
  "description": "Storefront search",
  "actions": ["documents:search"],
  "collections": ["products"],
  "expires_at": 1792108800,
  "value_prefix": "y7CF",
  "value": "y7CFw2zEgu09FFhoDgLzC99j0RwKi0kL"
}

IMPORTANT

This is the only time you'll see the key's value, so store it right away. If you lose it, you want to revoke the key and create a new one.

Revoke an API key ​

WARNING

Revoking a key can't be undone. So create the replacement key first, roll it out and then revoke the old one.

shell
curl -X DELETE --location "https://cloud.typesense.org/api/v1/clusters/<ClusterId>/api-keys/<KeyId>" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

<KeyId> is the key's id from List all API keys.

Response:

json
{
  "success": true
}

Error responses ​

  • HTTP 400 when a parameter isn't valid.
  • HTTP 400 when the cluster refuses the request, with the cluster's own message.
  • HTTP 404 when the cluster id is not on your account, or on revoke, when no key with that id exists on the cluster.
  • HTTP 422 when the cluster isn't in service.
  • HTTP 503 when the cluster can't be reached right now.

Permissions ​

To list, create or revoke keys, you need a key with the cluster_credentials:manage capability. See capabilities.