auth_token_invalid

Last updated Jun 14, 2026

Cause

Matter returns auth_token_invalid when the Authorization: Bearer … value on the request does not hash to any token row Matter has issued. The most common triggers are a copy-paste error that drops a trailing character, an environment swap where a sk_test_* token is sent to the live host, a token that was created against a different account, or a token whose secret half has been rotated since the request was prepared.

Matter never echoes the offending token back. The hash is computed in constant time against the active token table, and a single miss returns this error. There is no fuzzy match: a one-character change is treated the same as random bytes. This is deliberate — the error reveals nothing about which characters are right.

Fix

1. Verify the token is being read from the environment you think it is. Echo only the prefix (sk_test_ / sk_live_ / rk_* / pk_*) to confirm.
2. Confirm the host matches the token's mode. sk_test_* requires api.test.mattermode.com (or the Matter-Mode: test header on the live host); sk_live_* requires the live host.
3. If the token was rotated, fetch the new secret from your secrets manager and redeploy. The old secret is unusable from the moment rotation is finalised.
4. If none of the above applies, mint a fresh token from the dashboard or the createToken operation and update the caller.

Related codes

• auth_missing_credentials — no token was supplied at all.
• auth_token_revoked — the token was valid but has been revoked.
• auth_token_expired — the token was valid but has timed out.
• auth_token_mode_mismatch — the token resolved but its mode does not match the host.

API reference

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