> ## Documentation Index
> Fetch the complete documentation index at: https://developer.maatstays.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing your keys

> The one-time secret, scopes fixed at issue, rotation, revocation, and what "re-issue your key" means.

A key is the long-lived half of your credentials. An **integration** key opens exactly one
door — the [token exchange](/guides/authentication) — and everything you can actually do is
authorized by the short-lived token it mints. This page is the lifecycle of that key: how it
is issued, what it carries, and how it ends. (A **docs** key is the one exception and reaches
no workspace at all — see the end of this page.)

Getting your first one is [Get access](/guides/developer-access).

## What a key carries, and when

Four things are decided when a key is issued, and three of them can never change afterwards.

| Property | Decided | Changeable later |
| :- | :- | :- |
| The **workspace** | At issue | **No.** A key addresses one workspace and only that one. |
| Sandbox or Live | At issue | **No.** It is a property of the workspace the key was bound to. |
| The **scopes** | At issue | **No.** A key that needs another scope is a new key. |
| The **expiry** | At issue | Shortened by revoking and re-issuing; never extended. |

A key lives **365 days by default and never longer** — you can ask
for an earlier date at issue, never a later one, and "never expires" is not an option. A
self-issued credential whose answer to "when does this stop working?" is "never" is the
leaked-credential story the whole feature exists to bound.

## The secret is shown once

The screen that issues a key shows the secret once. Maat stores only a hash of it and
genuinely cannot show it again — not to you, not to support, not to an administrator.

* Copy it into a secret manager on that screen, before you leave it.
* Send it as `Authorization: Bearer maat_partner_…` **to the token exchange only**. It never
  authenticates a contract endpoint directly.
* Keep it out of a repository, a ticket and a screenshot. Where a tool wants it in a config
  file, put an environment variable there instead — the
  [MCP guide](/guides/connect-your-ai-assistant) shows that for the docs key, and the reason
  is the same for this one.

If you lose it, nothing can recover it. **Rotate** the key: a new secret is issued
immediately and the old one stops working, so update your integration first and rotate
second.

## Revocation takes effect on the next request

Revoking a key is immediate and cannot be undone. It also does not wait for a token to
expire: Maat re-reads the key row on **every** request behind a token, so a key revoked now
kills its outstanding tokens on their next call rather than up to an hour later.

The same re-read is why the token's `scope` claim is not what authorizes a call: the key row
is read fresh on every request, so nothing about your key can outlive a change to it. The
claim is your own identity echoed back for reading.

A key also stops working without anybody touching it in two cases: it reaches its expiry, or
the workspace it addresses is suspended. Both answer the same indistinguishable `401` as a
revocation.

## What "re-issue your key" means

Several entries in the [changelog](/guides/changelog) say a key issued before them "needs
re-issuing". They all mean the same narrow thing, and none of them means your integration is
broken:

**A new operation required a scope that no existing key was given.** Scopes are fixed at
issue, so there is no way to add one — the fix is a new key carrying it, and the old key
keeps working for everything it already did.

Concretely:

| To use | Your key needs | Given to keys issued before |
| :- | :- | :- |
| The read operations and the catalogues | `catalog:read` | No |
| `PUT /v1/listings/{listing_id}/pricing` | `pricing:write` | No |
| The photo write operations | `media:write` | No |
| The rate calendar and the pricing mode | `rates:read` / `rates:write` | No |
| The quick actions and the rules read | `rules:write` | No |

Everything else — the property push, calendar blocks, webhook registration — rides scopes
every key issued before those releases already holds. The
["Do I need to do anything?" table](/guides/changelog) at the top of the changelog is the
same information keyed by release.

A key you replace is not automatically revoked. Deploy the new one, confirm it works, then
revoke the old one — in that order, so a rollback is still possible.

## Two credentials that are not this key

* **The token.** Fifteen minutes by default, never more than an hour, minted per batch of
  work. Never store one. [Authentication](/guides/authentication).
* **The webhook signing secret.** A different secret entirely, for a different direction: it
  verifies deliveries **we** send **you**. It is issued once at registration, rotated through
  `POST /v1/webhooks/endpoint/rotate-secret`, and — unlike an API key — its rotation has an
  overlap window during which both secrets are honoured. [Webhooks](/guides/webhooks).

A docs key (`partner:mcp.read`) is a key like any other, and reaches no workspace at all —
[Scopes](/guides/scopes).


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