Tenant token payload reference

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.

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

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

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.

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": {}
}

In this example, the user will only receive medical_records documents whose user_id equals 1:

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

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"
  }
}

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

{
  "medical_records": {}
}

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"
  }
}

In this example, the user will receive documents from any index in the whole instance:

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

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",
  }
}

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.

Since a master key is not an API key, you cannot use a master key to create a tenant token. Avoid exposing API keys and always generate tokens on your application's back end.

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.