Authentication Errors

How to identify and resolve Protecto authentication and authorization failures.

Error response format

Authentication errors return a consistent JSON structure:

{
  "success": false,
  "error": {
    "message": "Authentication failed"
  }
}

Error scenario	Description
Missing token	`Authorization` header not provided
Invalid token	Token is malformed or not recognized
Expired token	Token is past its expiry date
Revoked token	Token has been deactivated
Insufficient permissions	Token is valid but not authorized for the requested operation

Work through this checklist when a request returns an authentication error:

Verify the Authorization header is present

Confirm the request includes Authorization: Bearer YOUR_TOKEN. The header name and Bearer prefix are required exactly as shown.

Check token expiry

Retrieve a fresh token from the Protecto portal if you suspect expiry. Protecto does not auto-refresh tokens.

Confirm permissions for the operation

Verify the token has the correct permission level. Unmask operations require explicit unmask permission — mask-only tokens cannot unmask.

Ensure the correct namespace

Tokens are namespace-scoped. Confirm the token belongs to the namespace targeted by the request.

Verify the policy exists

If policy_name is included in the request, confirm that policy exists in the namespace. A missing policy can trigger authorization failures.

Authentication failures always occur before masking or unmasking logic runs. If you receive an auth error, no data was processed.

Was this page helpful?

Last updated Mar 16, 2026