Multitenancy and tenant tokens

This guide shows you the main steps when creating tenant tokens using Meilisearch’s official SDKs.

There are two steps to use tenant tokens with an official SDK: generating the tenant token, and making a search request using that token.

Generate a tenant token with an official SDK

First, import the SDK. Then create a set of search rules:

{
  "patient_medical_records": {
    "filter": "user_id = 1"
  }
}

Search rules must be an object where each key corresponds to an index in your instance. You may configure any number of filters for each index.

Next, find your default search API key. Query the get API keys endpoint and inspect the uid field to obtain your API key’s UID:

cURL

curl \
  -X GET 'MEILISEARCH_URL/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

For maximum security, you should also define an expiry date for tenant tokens.

Finally, send this data to your chosen SDK’s tenant token generator:

JS

import { generateTenantToken } from 'meilisearch/token'

const searchRules = {
  patient_medical_records: {
    filter: 'user_id = 1'
  }
}
const apiKey = 'B5KdX2MY2jV6EXfUs6scSfmC...'
const apiKeyUid = '85c3c2f9-bdd6-41f1-abd8-11fcf80e0f76'
const expiresAt = new Date('2025-12-20') // optional

const token = await generateTenantToken({ apiKey, apiKeyUid, searchRules, expiresAt })

The SDK will return a valid tenant token.

Make a search request using a tenant token

After creating a token, you must send it your application’s front end. Exactly how to do that depends on your specific setup.

Once the tenant token is available, use it to authenticate search requests as if it were an API key:

JS

const frontEndClient = new MeiliSearch({ host: 'MEILISEARCH_URL', apiKey: token })
frontEndClient.index('patient_medical_records').search('blood test')

Applications may use tenant tokens and API keys interchangeably when searching. For example, the same application might use a default search API key for queries on public indexes and a tenant token for logged-in users searching on private data.

Next steps

Generate a token with a third-party library

Create tenant tokens using JWT libraries instead of Meilisearch SDKs.

Generate a token without any library

Build tenant tokens manually by assembling the JWT header, payload, and signature.

Tenant token payload reference

Learn about all available fields in the tenant token payload.

Manage API keys

Create, update, and delete API keys for your Meilisearch instance.