Skip to main content
A key is the long-lived half of your credentials. An integration key opens exactly one door — the token exchange — 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.

​
What a key carries, and when

Four things are decided when a key is issued, and three of them can never change afterwards. 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 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 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: 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 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.
  • 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.
A docs key (partner:mcp.read) is a key like any other, and reaches no workspace at all — Scopes.