Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Meilisearch’s tenant tokens are JSON web tokens (JWTs). Their payload is made of three elements: search rules, an API key UID, and an optional expiration date.
You can use jwt.io to inspect and debug tenant tokens during development. Paste a token into the tool to view its decoded header, payload, and signature.

​
Example payload

{
  "exp": 1646756934,
  "apiKeyUid": "at5cd97d-5a4b-4226-a868-2d0eb6d197ab",
  "searchRules": {
    "INDEX_NAME": {
      "filter": "attribute = value"
    }
  }
}

​
Search rules

The search rules object is a set of instructions defining search parameters Meilisearch enforces in every query made with a specific tenant token.

​
Search rules object

searchRules must be a JSON object. Each key must correspond to one or more indexes: 
{
  "searchRules": {
    "*": {},
    "INDEX_*": {},
    "INDEX_NAME_A": {}
  }
}
Each search rule object may contain a single filter key. This filter’s value must be a filter expression: 
{
  "*": {
    "filter": "attribute_A = value_X AND attribute_B = value_Y"
  }
}
Meilisearch applies the filter to all searches made with that tenant token. A token only has access to the indexes present in the searchRules object. A token may contain rules for any number of indexes. Specific rulesets take precedence and overwrite * rules.
Because tenant tokens are generated in your application, Meilisearch cannot check if search rule filters are valid. Invalid search rules throw errors when searching.Consult the search API reference for more information on Meilisearch filter syntax.
The search rule may also be an empty object. In this case, the tenant token will have access to all documents in an index: 
{
  "INDEX_NAME": {}
}

​
Examples

​
Single filter

In this example, the user will only receive medical_records documents whose user_id equals 1: 
{
  "medical_records": {
    "filter": "user_id = 1"
  }
}

​
Multiple filters

In this example, the user will only receive medical_records documents whose user_id equals 1 and whose published field equals true: 
{
  "medical_records": {
    "filter": "user_id = 1 AND published = true"
  }
}

​
Give access to all documents in an index

In this example, the user has access to all documents in medical_records: 
{
  "medical_records": {}
}

​
Target multiple indexes with a partial wildcard

In this example, the user will receive documents from any index starting with medical. This includes indexes such as medical_records and medical_patents: 
{
  "medical*": {
    "filter": "user_id = 1"
  }
}

​
Target all indexes with a wildcard

In this example, the user will receive documents from any index in the whole instance: 
{
  "*": {
    "filter": "user_id = 1"
  }
}

​
Target multiple indexes manually

In this example, the user has access to documents with user_id = 1 for all indexes, except one. When querying medical_records, the user will only have access to published documents: 
{
  "*": {
    "filter": "user_id = 1"
  },
  "medical_records": {
    "filter": "user_id = 1 AND published = true",
  }
}

​
API key UID

Tenant token payloads must include an API key UID to validate requests. The UID is an alphanumeric string identifying an API key: 
{
  "apiKeyUid": "at5cd97d-5a4b-4226-a868-2d0eb6d197ab"
}
Query the get one API key endpoint to obtain an API key’s UID. The UID must indicate an API key with access to the search action. A token has access to the same indexes and routes as the API key used to generate it. Avoid exposing API keys and always generate tokens on your application’s back end.
If an API key expires, any tenant tokens created with it will become invalid. The same applies if the API key is deleted.

​
Expiry date

The expiry date must be a UNIX timestamp or null: 
{
  "exp": 1646756934
}
A token’s expiration date cannot exceed its parent API key’s expiration date. Setting a token expiry date is optional, but highly recommended. Tokens without an expiry date remain valid indefinitely and may be a security liability.
The only way to revoke a token without an expiry date is to delete its parent API key.