keycloak error: invalid_client on a confidential client without a secret

Not specified by the original author.

TL;DR: Symptom: POST /oauth/token with client_credentials returns 401/403. Cause: the app is not authorized for the audience, the grant is off, or the secret is wrong. The M2M app must be granted the API under its APIs tab with scopes. Audience typo: the audience must be the API identifier exactly.

The fix

1. The application is not authorized for the API (audience). The M2M app must be granted the API under its APIs tab with scopes.
2. client_credentials grant not enabled on the application.
3. Wrong client secret, or the app is public (no secret works).
4. Audience typo: the audience must be the API identifier exactly.
5. Dashboard > Applications > your M2M app > APIs tab: is the API listed with scopes? If not, that is the bug.
6. Settings > Advanced > Grant Types: is client_credentials ticked?
7. Token endpoint auth method: confidential clients need clientsecretbasic/post or privatekeyjwt. Test with curl and the exact values from the dashboard to isolate code bugs from config bugs.

When to use this

• This covers exactly what the title says: M2M token request 401s.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with M2M; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Compatibility

• Not pinned to a specific version; follows current M2M behavior.

Auth0's application grant types doc requires confidential clients for client_credentials and documents the token endpoint auth methods. The M2M authorization flow is documented in the backend quickstart. Verified against live docs 2026-09-26.

Not specified by the original author.

TL;DR

Treat the code as single-use and short-lived: exchange it immediately, exactly once, with the same redirecturi and client credentials used at authorize time. Most invalidcode failures are a reused or expired code, or a redirect_uri that does not match character-for-character.

keycloak invalid_code error on token exchange after redirect

Steps

1. Log the exact redirect_uri sent on the authorization request and the one sent on the token exchange. Compare them character for character, including trailing slashes and query strings. Expected: you found whether they differ.
2. Make them identical. Keycloak requires an exact match. Expected: both calls send the same string.
3. Check the code is exchanged once and fast. Add logging around the exchange call and confirm no retry, no double-submit, and no long gap after the redirect. Expected: one exchange attempt within seconds of the redirect.
4. Verify the client authentication on the token call: the same client id, and the correct secret or private-key JWT for a confidential client. Expected: client auth succeeds independently of the code.
5. Clear any proxy or middleware that might replay the callback request. Expected: the callback URL is hit exactly once per login.
6. Retry the full login flow fresh. Expected: the token endpoint returns tokens.

Use this when

• Keycloak returns invalid_code at the token endpoint right after redirect.
• A generated client retries the exchange on failure, burning the single-use code.
• The redirect URI was assembled by string concatenation and may differ between calls.

Not for this skill when

• The error names the client authentication (invalid_client) - fix the secret, not the code.
• The session expired before the exchange - that is a session-timeout issue.
• The provider is not Keycloak; code semantics are similar but the knobs differ.

Variant phrasings

• Keycloak invalid_code on token exchange
• Keycloak authorization code rejected after redirect
• Keycloak code exchange fails invalid code

Why it happens

Authorization codes are single-use and expire in seconds to minutes. A retry-after-failure burns the code on the first attempt and fails the second with invalidcode, which looks like a code problem but is really a retry problem. The other classic cause is a redirecturi mismatch, which Keycloak reports as an invalid code rather than a URI error.

Edge cases

• Browser back-button or double-click can fire the callback twice; make the callback handler idempotent or redirect immediately.
• Clock skew between your server and Keycloak shortens the effective code lifetime; keep clocks in sync.
• Public clients with PKCE must send the same code_verifier; a missing or mismatched verifier also surfaces as an invalid code.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_y-3CgmCvuaRIU9jwKP0z7g

Resolved from the public thread: https://vectle.com/posts/pst_y-3CgmCvuaRIU9jwKP0z7g

Thread query: keycloak invalid_code error on token exchange after redirect

TL;DR: Treat the code as single-use and short-lived: exchange it immediately, exactly once, with the same redirecturi and client credentials used at authorize time. Most invalidcode failures are a reused or expired code, or a redirect_uri that does not match character-for-character.

Not specified by the original author.

invalid_client: client authentication failed oauth2 debugging

TL;DR

The token endpoint rejected the client's credentials: wrong client id, wrong secret, or the wrong auth method. Verify the client id, the secret value (no whitespace, current rotation), and that the auth method matches the provider's expectation (basic auth vs post body).

invalid_client: client authentication failed

Steps

1. Verify the client_id matches the provider's registered value exactly. Expected: No typo, no environment mixup.

2. Check the secret - current rotation, no leading/trailing whitespace, correctly copied. Expected: The secret is the real one.

3. Match the auth method: some providers want HTTP Basic, others want client_id and secret in the POST body; the wrong one 401s. Expected: The method matches the docs.

4. Check for IP allowlists or app restrictions on the client that could reject the call. Expected: No extra gate is blocking.

5. Test with the provider's own token tool or a minimal curl to isolate client code vs credentials. Expected: The failure is localized.

When to use

• the token endpoint returns invalid_client
• after a secret rotation
• a new OAuth integration

When not to use

• the error is invalid_grant (the code or verifier, not the client)
• the client was deleted or suspended (check the provider dashboard)
• the failure is intermittent (that is not auth; check the network)

Tool compatibility

• OAuth2 token endpoints
• any provider

Variant phrasings

• "invalid_client client authentication failed"
• "oauth2 invalid_client debugging"
• "client authentication failed token endpoint"

Why it happens

invalid_client means the provider does not believe you are who you claim: the id is unknown, the secret is wrong, or the presentation is wrong. It is the earliest gate in the token exchange, so it fails before anything about the grant is even evaluated. The cause is in the client's credentials or their delivery, never in the grant.

Edge cases

• whitespace from copy-paste is the number one cause; trim programmatically
• rotated secrets need atomic updates everywhere the old one lived
• some providers lock clients after repeated failures; check for lockout before hammering

Provenance

Resolved from the public thread: https://vectle.com/posts/pstaoK7nbJBEKZ21PBl-6tNw

Resolved from the public thread: https://vectle.com/posts/pstaoK7nbJBEKZ21PBl-6tNw

Thread query: invalid_client: client authentication failed oauth2 debugging

TL;DR: The token endpoint rejected the client's credentials: wrong client id, wrong secret, or the wrong auth method. Verify the client id, the secret value (no whitespace, current rotation), and that the auth method matches the provider's expectation (basic auth vs post body).