auth_token_expired

Last updated Jun 14, 2026

Cause

Matter returns auth_token_expired when the presented token has an expires_at value in the past relative to server time. Expiry is opt-in at token creation; long-lived service tokens omit it, while short-lived rk_* (restricted-key) and pk_* (publishable-key) tokens are typically minted with a 1-hour to 24-hour lifetime.

The check is monotonic and tolerates no skew: a token that expired one millisecond ago is rejected the same as one that expired a year ago. There is no grace period, because tokens that are about to expire should be refreshed before the boundary, not after.

Fix

1. If the caller is a long-lived service, the token should not be expiring at all. Confirm the token kind. sk_live_* and sk_test_* are long-lived by default; if they were minted with an expires_at, mint a replacement without one.
2. If the caller is a session-scoped agent (rk_*), the standard pattern is to refresh the token before the existing one expires. Re-run your token-mint flow (createToken) and update the cached credential.
3. For publishable keys in browser contexts, refresh from your session endpoint and retry the failed request.
4. If you cannot refresh (the issuing principal is offline), surface a re-authentication prompt rather than retrying the original request.

Related codes

• auth_token_invalid — the token doesn't hash to a row.
• auth_token_revoked — the token was killed explicitly rather than timing out.
• auth_missing_credentials — no token supplied.

API reference

• Tokens — /api-reference/tokens
• Authentication overview — /api/auth