# Troubleshooting: identity

> Refused tokens, scopes, API keys, client certificates and CORS origins: the symptom, its cause and what to do.

Troubleshooting - Since version 0.3.0 - Flexway v1.7.1 - https://flexway.io/en/docs/operations-troubleshooting-identity/

> Operations guide: configure, deploy and observe the gateway. What the feature does, product side: [product guide](https://flexway.io/en/docs/product-overview/); calling it: [developer guide](https://flexway.io/en/docs/developer-overview/).

| Symptom | Cause | Action |
| --- | --- | --- |
| `401` on valid tokens right after a start | The issuer's keys are not loaded yet | The log says `issuer not reachable yet`; check the gateway reaches the discovery URL |
| `401` `invalid_token` on a token that works elsewhere | Audience, issuer or algorithm: the reason is in the log (`token refused`), never in the response | Compare the token's `aud` and `iss` with `auth.issuers` |
| `403` `insufficient_scope` | The token lacks the scope or role the **contract** requires | Read `scope=` in `WWW-Authenticate`; for a role, check `roles_claim` |
| `401` `WWW-Authenticate: ApiKey` on a key believed good | Unknown key (removed, mistyped), expired, or without the `fwk_` prefix | The log (`API key refused`) gives the cause and, for an expired key, its `id`; create a new one |
| `401` "does not accept API keys" | The operation has no `apiKey` alternative in the contract | Add `{ key: [] }` to its `security`, if intended |
| `403` "not bound to this operation" (key or certificate) | The entry does not name this operation | Add the `operationId` to the entry's `operations`; reload |
| Refused at load "no contract declares" on a key or a certificate | The entry names an operation that does not exist (renamed?) | Fix the `operationId` |
| `401` "requires a client certificate" despite a certificate | Undeclared certificate, or `x-forwarded-client-cert` from a peer outside `server.trusted_proxies` | Check the URI SAN or subject against `auth.mtls.clients`; declare the edge's range |
| TLS handshake refused on `:8443` | A client certificate from another authority than `client_ca_file` | Add the authority to the file: it is re-read without a restart |
| `403` "This origin is not allowed" | The browser's origin is in no `cors` policy | Add it to `allow_origins` |