Imported from overlens/claude-marketplace (plugins/idp-integration/skills/idp-troubleshoot-auth-errors/SKILL.md). Install upstream with npx skills add overlens/claude-marketplace --skill idp-troubleshoot-auth-errors. Copyright stays with the author.

Overlens IDP — Troubleshooting Auth Errors

This skill turns a symptom (a status code, a missing cookie, a CORS console error) into a cause and a fix. It exists because most IDP integration tickets are not "how do I integrate" — they're "I integrated and I'm stuck on this one error," and the same dozen errors recur. Each one has a precise, known cause.

Scope: HTTP/transport/config failures — status codes, cookies, CORS, rate limits. If the request succeeds and returns a token but the token itself is wrong (wrong iss/aud, kid not found, signature fails, you need to decode the payload), that's a different problem → use idp-debug-jwt.

Canonical docs (track the code; this skill curates them): https://github.com/overlens/identity-provider/blob/main/docs/deploy/railway.md §11 (the primary troubleshooting list), ../../references/docs/integration/frontend.md §4 (error reference table), ../../references/docs/integration/login.md §10 (token-endpoint errors), ../../references/docs/deploy/rate-limiting.md (rate-limit profiles).

How to use this skill: diagnose before you fix

Resist the urge to guess. The IDP's OAuth errors are deliberately precise — the error field in the body and the exact Set-Cookie/CORS headers tell you the cause. Capture the full response first, then read it off the table. Two minutes of curl -i saves an hour of speculation.

What you need before consulting the tables below:

1. The exact status code (401 ≠ 403 ≠ 429 — they have unrelated causes).
2. The error field in the JSON body — invalid_client, unauthorized_client, invalid_grant, invalid_scope, invalid_redirect_uri are different errors that can share a status code.
3. Which endpoint — /auth/token, /auth/authorize, /login, /login/google, /token/refresh. The same code means different things per endpoint.
4. Response headers (-i in curl, Network tab in the browser) — for cookie and CORS problems the body is empty; the headers ARE the diagnosis.
5. Does it fail in dev, prod, or only prod? "Works locally, breaks in production" is itself a strong signal (almost always CORS, cookie Secure/domain, or a missing env var).

The recipes in references/diagnostic-recipes.md give you copy-paste curl/browser commands to capture each of these. Reach for them when the cause isn't obvious from the description.

Master table: symptom → cause → fix

Find your row. The detailed sections below expand the ones that bite hardest.

The errors that bite hardest (detail)

401 invalid_client on /auth/token — the #1 token-exchange failure

This is the back-channel credential check failing. It is always one of:

• client_id typo or not seeded in the IDP
• wrong client_secret (rotated? copied with a trailing newline? wrong environment's secret?)
• the Authorization: Basic header is malformed — it must be base64("<client_id>:<client_secret>"), the two values joined by a literal colon, then base64'd as one string
• a public client (mobile/SPA, isPublic:true) trying to authenticate as confidential by sending a secret — public clients authenticate with PKCE, not a secret

The response always includes WWW-Authenticate: Basic realm="IDP". Confirm the secret round-trips: base64-decode your Basic header and eyeball the id:secret. The most common real cause is an env var that's empty in the deployed environment but set locally — print it (masked) on boot.

400 unauthorized_client vs 400 unsupported_grant_type — don't conflate them

Both are 400s on /auth/token, but:

• unsupported_grant_type: the grant_type value isn't one the IDP knows. The only valid values are authorization_code, refresh_token, client_credentials. The classic trap is grant_type=revoke — it does not exist (RFC 7009 per-token revocation is not implemented). If you're trying to log out, you're in the wrong place: logout is NOT a /auth/token call. Navigate the browser (top-level, not fetch) to the GET /auth/logout end_session_endpoint with client_id + a registered post_logout_redirect_uri + state → see the integration skills (idp-integrate-oauth-web, idp-auth-nextjs).
• unauthorized_client: the grant exists, but this client isn't allowed to use it. An M2M client asking for refresh_token, or a web client asking for client_credentials, gets this. Fix the request or the client's allowedGrantTypes.

400 invalid_redirect_uri — exact match, every character counts

The IDP validates redirect_uri against the registered list by exact string match. These are all different URIs and three of them will be rejected if only one is registered:

• https://app.overlens.com.br/api/auth/callback
• https://app.overlens.com.br/api/auth/callback/ ← trailing slash
• http://app.overlens.com.br/api/auth/callback ← http
• https://app.overlens.com.br:443/api/auth/callback ← explicit port

Register the URI your code actually sends, byte-for-byte. In dev that's usually http://localhost:PORT/...; in prod the https domain. Both must be registered. This is a configuration error surfaced to the developer, never shown to the end user.

404 on POST /login/google — it's a feature flag, not a missing route

A 404 here is almost never a wrong URL. The endpoint is gated by the PostHog feature flag idp_google-auth; when the flag is off — or PostHog isn't configured (POSTHOG_API_KEY unset), since flags fail closed — the guard answers 404 Not Found for every call. Check the PostHog panel; in the meantime hide the Google button. (This gate applies to the cookie-mode /login/google only. The OAuth-path Google endpoints — /auth/authorize/google, /auth/signup/google — are NOT behind this flag; see ../../references/docs/integration/login.md and ../../references/docs/integration/signup.md.)

429 Too Many Requests — which profile did you hit?

Rate limits are per IP (per client for M2M reads) and per-route. Every 429 carries a standard Retry-After header (seconds). Effective limits:

Counting is per route — blowing the /login bucket does not affect /auth/token.

Common triggers and fixes:

• CI / smoke tests doing repeated logins from one IP blow the 10/min /login bucket (per-IP, so one CI runner = one bucket). Reuse the session (refresh instead of re-login), use a staging IDP with IDP_RATE_LIMIT_DISABLED=true, or allowlist the CI IP at Cloudflare.
• M2M service hitting 429 on /auth/token = you're fetching a token per request instead of caching it. A cached 5-min token hits the IDP ~once per 5 min, nowhere near 30/min. → idp-integrate-m2m.
• Note: the throttler is active in every environment (since 2026-07-14 — before that it was disabled everywhere). A 429 is reproducible locally. Kill-switch: IDP_RATE_LIMIT_DISABLED=true (ops/load-test only). Redis (REDIS_URL) is required for the count to be global across instances.

Max-Age=0 cookies — the milliseconds bug

If a user is logged out the instant they log in, inspect the Set-Cookie header: Max-Age=0 means the browser was told to delete the cookie immediately. Cause: Express's res.cookie({ maxAge }) expects milliseconds and divides by 1000 internally, so maxAge: 900 becomes Max-Age=0. The IDP uses 900_000 (15 min) and 2_592_000_000 (30 d) on purpose. This is an IDP-side regression — if you see it in production after a change, that change broke the cookie helper. Verify:

curl -i -X POST https://idp.overlens.com.br/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"u@x.com","password":"x"}' | grep -i max-age
# Expected: Max-Age=900 and Max-Age=2592000  (NOT Max-Age=0)

Cookies missing / CORS fails in prod but not dev

These two travel together because both are about cross-origin browser rules:

• No Set-Cookie applied: a fetch to the IDP without credentials: 'include' won't store or send cookies. But step back — cookie-mode only works for SPAs hosted under *.overlens.com.br. The cookies are scoped to .overlens.com.br; an app on any other domain will never receive them. If that's you, you shouldn't be calling the IDP directly at all → use OAuth (idp-integrate-oauth-web / idp-auth-nextjs).
• CORS error only in production: the IDP allows browser origins matching \.overlens\.com\.br$. A prod frontend on a different domain fails the preflight even though localhost worked in dev (dev CORS is permissive). The real fix is usually architectural: frontends should never call the IDP directly — they redirect to accounts.overlens.com.br and let their own server-side BFF do the token exchange. If you're hitting CORS on the IDP from browser JS, that call is in the wrong place.

"Works locally but breaks in production" — the prod-only checklist

A large share of tickets are this. When dev is green and prod is red, walk these in order:

1. Missing/empty env var in prod — IDP_CLIENT_SECRET, IDP_BASE_URL, GOOGLE_CLIENT_ID, etc. set locally but not in Railway. Causes 401 invalid_client, wrong discovery URLs, or 404 Google. Print them masked on boot.
2. CORS origin — prod origin not under \.overlens\.com\.br$ (see above).
3. Cookie Secure/Domain — prod is HTTPS so Secure cookies work, but if IDP_COOKIE_DOMAIN is wrong the Domain=.overlens.com.br attribute is missing and cookies go host-only.
4. redirect_uri not registered for the prod domain — dev registered http://localhost:..., prod sends https://app.overlens.com.br/... which was never registered → 400 invalid_redirect_uri.
5. Rate limiting counts per instance without Redis — the throttler is active in every environment, but without REDIS_URL each instance keeps its own count. Prod (multi-instance + Redis) can 429 earlier than your single local instance.
6. PostHog flag — Google login answers 404 in prod if the flag/env isn't set, even though dev may have bypassed it.

When it's NOT this skill

Route correctly — these symptoms look adjacent but belong elsewhere:

• Token received but rejected by your Resource Server (iss/aud mismatch, kid not found, signature verify fails, "is this token even valid?", decode the payload) → idp-debug-jwt.
• You haven't integrated yet, nothing is erroring → the integration skills (idp-integrate-oauth-web, idp-auth-nextjs, idp-auth-vite-bff, idp-auth-mobile, idp-integrate-m2m, idp-validate-token).
• Logout specifically (the revoke trap, the GET /auth/logout end_session_endpoint, post_logout_redirect_uri) → the integration skills (idp-integrate-oauth-web, idp-auth-nextjs).
• Registering an OAuth client / fixing its allowedGrantTypes/redirectUris/allowedScopes → idp-register-oauth-client.

Where the real docs live

This skill curates them; they track code changes:

• https://github.com/overlens/identity-provider/blob/main/docs/deploy/railway.md §11 — the primary, maintained troubleshooting list
• ../../references/docs/integration/frontend.md §4 — front-end error reference table
• ../../references/docs/integration/login.md §10 — token-endpoint error reference
• ../../references/docs/deploy/rate-limiting.md — full per-route limits, per-IP/per-client keying, kill-switch

When a fix here disagrees with those, the docs win — re-sync this skill.

File map of this skill

idp-troubleshoot-auth-errors/
├── SKILL.md                          (this file — triage + symptom→cause→fix tables)
└── references/
    └── diagnostic-recipes.md         (copy-paste curl/browser commands to capture the symptom)

Read references/diagnostic-recipes.md when the cause isn't obvious from the report and you need to reproduce/capture the exact response.