Authentication errors

A 401 response carries one of the authentication-specific codes:

code	Meaning
missing_api_key	The Authorization header was not present on the request.
invalid_api_key	The key was malformed, expired, revoked, or of the wrong type (for example, a pat_… token sent to /v1/*).
api_key_env_mismatch	The key's prefix (sk_test_ / sk_live_) disagrees with the environment the key was issued for. See Wrong-environment keys below.
unauthorized	A generic authentication failure that does not map to one of the codes above.

A 403 response is an authorization failure, not authentication:

code	Meaning
ip_not_allowed	The caller's IP is not on the account's IP allowlist.
missing_scope	The key does not carry the scope required for this operation.
forbidden	A generic authorization failure.
allowlist_check_failed	A configured allowlist rejected the request (e.g. recipient domain).

Wrong-environment keys

The api_key_env_mismatch error fires when the prefix of the API key you sent (sk_test_ or sk_live_) does not match the environment that key was originally issued for. Common causes:

• Copying a sandbox key (sk_test_…) into a production environment variable.
• Copying a production key (sk_live_…) into a staging or test environment.
• A deployment pipeline that promotes secrets across environments without updating them.

Suggested action: rotate to a key that belongs to the correct environment. You can generate new keys in the Permissio dashboard under Settings → API keys. Make sure each environment (sandbox, production) uses a key with the matching prefix.