API v1 · 4xx
invalid_token
| HTTP | When |
|---|---|
| 401 | The token format is invalid, doesn't match a known key, or the workspace lost its Clerk binding mid-flight. |
Common causes:
- Mistyped or truncated token. Re-copy from your password manager and retry.
- The token was minted in a different environment (live vs test) than
the one you're hitting. Double-check the prefix
(
scripe_sk_live_vsscripe_sk_test_). - The token was revoked very recently and the cached row was already evicted, so the request makes it past the cache and finds no live row. Mint a new key.
- (Rare) the workspace was deleted or its Clerk org binding broke. We fail closed in that case to avoid leaking row-existence signals.
If you've copy-pasted from a password manager, ensure no leading or trailing whitespace was included. Many secret stores strip newlines on copy but not on autofill.
OAuth access tokens (scripe_oat_*)
The same code covers four different situations on the OAuth path, and
the message / error_description says which one — read it rather
than the code, because the repairs differ:
| Message says | What to do |
|---|---|
| does not look like a Scripe OAuth access token | You presented something else (often an API key — those are REST-only). |
| is not recognised | The token belongs to another environment, or it has already been rotated away. Get a fresh one. |
expired at <timestamp> | Refresh it with your refresh token. |
| has been revoked | Re-run the authorization flow. Refreshing will fail too: this is what happens when a connection is disconnected, or when a refresh token is presented twice — reuse revokes the whole token family, so two clients sharing one grant will take each other down. |
Two neighbours are deliberately not invalid_token, because
re-authorizing cannot fix either: a consent the user revoked answers
consent_required, and a
Scripe-Workspace-Id header naming a workspace the user is not a member
of answers 400 workspace_unavailable.