# API Keys

Typesense allows you to create API Keys with fine-grain access control. You can restrict access on both a per-collection and per-action level.

WARNING

We will be using the initial bootstrap key that you started Typesense with (via --api-key>) to create additional keys. It's strongly recommended that you don't use the bootstrap API key directly in your production applications. Instead you want to generate an appropriately-scoped key for the application at hand.

# Create an API Key

Let's begin by creating an API key that allows you to do all operations, i.e. it's effectively an admin key and is equivalent to the key that you start Typesense with (via --api-key).

By setting both actions and collections to a wildcard ['*'] scope, we're able to create an admin key that gives you universal access. However, you should refrain from creating such widely scoped keys.

WARNING

The generated key is only returned during creation. You want to store this key carefully in a secure place.

Let's now see how we can create a search-only key that allows you to limit the key's scope to only the search action, and also for only a specific collection.

By setting the actions scope to ["documents:search"] and the collections scope to ["companies"], we can generate a key that is allowed to only conduct searches on the companies collection.

# Sample Response

# Definition

POST ${TYPESENSE_HOST}/keys

# Arguments

Parameter Required Description
actions yes List of allowed actions. See next table for possible values.
collections yes List of collections that this key is scoped to. Supports regex. Eg: coll.* will match all collections that have "coll" in their name.
description no Internal description to identify what the key is for
expires_at no Unix timestamp (opens new window) until which the key is valid.

# Sample actions

Action Description
documents:search Allows only search requests.
documents:get Allows fetching a single document.
collections:delete Allows a collection to be deleted.
collections:create Allows a collection to be created.
collections:* Allow all kinds of collection related operations.
* Allows all operations.

# Retrieve an API Key

Retrieve (metadata about) a key.

# Sample Response

Notice how only the key prefix is returned when you retrieve a key. Due to security reasons, only the create endpoint returns the full API key.

# Definition

GET ${TYPESENSE_HOST}/keys/:id

# List all Keys

Retrieve (metadata about) all keys.

# Sample Response

Notice how only the key prefix is returned when you retrieve a key. Due to security reasons, only the create endpoint returns the full API key.

# Definition

GET ${TYPESENSE_HOST}/keys/

# Delete API Key

Delete an API key given its ID.

# Sample Response

# Definition

DELETE ${TYPESENSE_HOST}/keys/:id

# Generate Scoped Search Key

You can generate scoped search API keys that have embedded search parameters in them. This is useful for example when you have multi-tenant data indexed in your Typesense instance, but only want your users to access their own subset of the data.

To do this, you can embed a filter in a generated scoped search API key. When you use that key for search operations, those filters will get automatically applied and cannot be overriden.

We can generate scoped search API keys without having to make any calls to the Typesense server. We use an API key that we previously generated with a search scope, create an HMAC digest of the parameters with this key and use that as the API key. Our client libraries handle this logic for you, but you can also generate scoped search API keys from the command line.

WARNING

Remember to never expose your main search key client-side, since exposing the main search key will allow anyone to query the entire data set without your embedded search parameters.

# Sample Response

You can also set a custom expires_at for a scoped API key. The expiration for a scoped API key should be less than the expiration of the parent API key with which it is generated.

Last Updated: 7/11/2021, 11:35:46 AM