# Authentication troubleshooting

Authentication failures should be diagnosed by credential type first. Dashboard sessions and API keys are intentionally not interchangeable on every endpoint.

## Symptom

The server returns HTTP 401 or 403, sign-in attempts are temporarily rejected, or an API request that works in the dashboard fails with a Bearer credential. A state-changing browser request may also fail because its request-intent header is missing.

## Cause

HTTP 401 means the session is absent or expired, or the API key is invalid or revoked. HTTP 403 means the identity is known but the endpoint, workspace role, or credential type is not allowed. Repeated sign-in attempts can trigger a short rate limit. Dashboard-only endpoints reject API keys even when the key itself is valid.

## Verify

Confirm whether the request uses `Authorization: Bearer YOUR_API_KEY` or the `cx_session` cookie. Compare that choice with the operation page. For a cookie-authenticated `POST`, `PUT`, `PATCH`, or `DELETE`, verify `X-CX-Request: 1`. Do not send both credentials while debugging because an invalid Bearer value is not allowed to fall back to a browser session.

## Recovery

For an expired session, sign in again. For a revoked key, create a replacement in the dashboard and update the caller; keys cannot be recovered after creation. For `rate_limited`, wait for the duration in `details.retry_after_seconds` before another sign-in attempt. Use a human session for dashboard-only operations.

## Escalation

Escalate after a newly issued credential still fails against the correct workspace and documented operation. Share the operation path, status, code, UTC time, and credential type, never the credential value. Read [API authentication](/docs/reference/api/authentication) and [Workspace API keys](/docs/workspace/api-keys) before escalation.

## Error code index

- `rate_limited` — pause sign-in attempts for the returned retry interval.
- `unauthenticated` — sign in again or replace the invalid or revoked API key.

Logout is a special case: `POST /api/v1/auth/logout` does not require authentication. If a session cookie is present, the browser mutation still passes through request-intent protection. HTTP 204 means the server session was revoked, but the response does not guarantee removal of the stored cookie. A non-browser or API client should discard it from the cookie jar. Browser JavaScript cannot remove the `HttpOnly` cookie; a browser user should sign in again so the cookie is replaced, or clear site data or cookies through browser settings before the next sign-in.