> ## 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.

# 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.

Meilisearch's tenant tokens are JSON web tokens (JWTs). Their payload is made of three elements: [search rules](#search-rules), an [API key UID](#api-key-uid), and an optional [expiration date](#expiry-date).

> [!TIP]
>
> You can use [jwt.io](https://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

```json theme={null}
{
  "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:

```json theme={null}
{
  "searchRules": {
    "*": {},
    "INDEX_*": {},
    "INDEX_NAME_A": {}
  }
}
```

Each search rule object may contain a single `filter` key. This `filter`'s value must be a [filter expression](https://www.meilisearch.com/docs/capabilities/filtering_sorting_faceting/advanced/filter_expression_syntax.md):

```json theme={null}
{
  "*": {
    "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.**

> [!WARNING]
>
> 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](https://www.meilisearch.com/docs/reference/api/search/search-with-post.md#body-filter).

The search rule may also be an empty object. In this case, the tenant token will have access to all documents in an index:

```json theme={null}
{
  "INDEX_NAME": {}
}
```

### Examples

#### Single filter

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

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "*": {
    "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:

```json theme={null}
{
  "*": {
    "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:

```json theme={null}
{
  "apiKeyUid": "at5cd97d-5a4b-4226-a868-2d0eb6d197ab"
}
```

Query the [get one API key endpoint](https://www.meilisearch.com/docs/reference/api/keys/get-api-key.md) to obtain an API key's UID.

The UID must indicate an API key with access to [the search action](https://www.meilisearch.com/docs/reference/api/keys/create-api-key.md#body-actions). 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**.

> [!WARNING]
>
> 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`:

```json theme={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.

> [!WARNING]
>
> The only way to revoke a token without an expiry date is to [delete](https://www.meilisearch.com/docs/reference/api/keys/delete-api-key.md) its parent API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.