Token lifecycle

This page sets out how each kind of credential is issued, checked, refreshed and ended, and how long each one lasts. For the overview, read Authentication.

API keys #

Issuance #

1. An owner or admin creates a key on the API keys page.
2. The creator chooses an expiry: 30 days, 90 days (the default), 1 year, or never. A key set to never has no expiry date.
3. The server generates a random secret with the prefix mdt_live_ in production or mdt_test_ elsewhere.
4. The server stores a SHA-256 hash of the secret. The plaintext is shown once, then discarded.

Each request #

1. The bearer token is hashed and looked up.
2. The key must not be revoked or expired, and its owner must still be an active member of the key's workspace.
3. The server records when the key was last used. The key list shows that date.
4. The key's scopes decide which tools the request may call.

Revocation and rotation #

Revoking a key sets its revoked time. The next request gets 401. Rotating a key revokes it and issues a new secret with the same name, scopes and expiry.

OAuth access and refresh tokens #

Authorisation code #

An authorisation code lasts 5 minutes and works once. It is bound to a PKCE challenge, so only the app that started the flow can redeem it.

Access token #

An access token lasts 1 hour. Each request checks that it has not expired or been revoked.

Refresh token #

A refresh token lasts 30 days from the first approval. Each refresh issues a new access token and a new refresh token, and the new refresh token keeps the original 30-day deadline. The window is absolute, not sliding, so a client that refreshes every hour cannot keep a grant alive indefinitely. After 30 days the person approves the app again.

The access and refresh lifetimes are tracked separately. A refresh works while the refresh window is open, even after the access token has expired.

Storage #

Access tokens, refresh tokens and authorisation codes are stored as hashes. Each raw token is returned to the client once.

Ending a credential #

Lifetimes at a glance #