Slack error oauth_authorization_url_mismatch: OAuth flow started on the wrong authorize URL
Last verified against Slack API reference - chat.postMessage errors
The OAuth flow was initiated on an incorrect version of the authorization url. The flow must be initiated via /oauth/v2/authorize.What error oauth_authorization_url_mismatch means
You are finishing the install with oauth.v2.access, but the user started it on a different version of Slack's authorize page. The docs say "The OAuth flow was initiated on an incorrect version of the authorization url. The flow must be initiated via /oauth/v2/authorize."
Slack's OAuth has two versions, and each step must match. The current flow sends users to https://slack.com/oauth/v2/authorize, with bot scopes in scope and user scopes in user_scope, then exchanges the code with oauth.v2.access. Codes from the older /oauth/authorize page cannot be exchanged by the v2 method.
This usually happens in apps that were upgraded halfway: the backend moved to oauth.v2.access, but an old "Add to Slack" button on a marketing page, docs page or email still links to the v1 URL. Your credentials are correct; the starting link is outdated.
What it looks like
Started at: https://slack.com/oauth/authorize?client_id=...&scope=...
Exchange: POST /api/oauth.v2.access
{"ok": false, "error": "oauth_authorization_url_mismatch"}Why it happens
- An old Add to Slack button or bookmarked install link still points to /oauth/authorize.
- The backend was migrated to oauth.v2.access but the authorize URL was not.
- A library or plugin builds a v1 authorize URL by default.
How to fix Slack error oauth_authorization_url_mismatch
- 1Find every install link (site, docs, emails, app directory listing) and point it to https://slack.com/oauth/v2/authorize.
- 2Pass bot scopes as scope and user scopes as user_scope in the v2 URL.
- 3Generate the authorize URL in one place in code instead of hard-coding it in pages.
- 4Have the user start the install again from the corrected link.
How to stop it recurring
Serve the install link from one backend route that redirects to the v2 authorize URL, and link to that route everywhere. Then old pages never hold Slack URLs directly, and future changes happen in one place. Search old marketing pages and emails for /oauth/authorize when you migrate.
Official reference: Slack API reference - chat.postMessage errors. See all Slack error codes or the Slack limits and quotas.
Related codes
- invalid_code: OAuth authorization code is invalidValue passed for code was invalid.
- bad_redirect_uri: redirect_uri does not match the original requestValue passed for redirect_uri did not match the redirect_uri in the original…
- bad_client_secret: client_secret is invalidValue passed for client_secret was invalid.
- missing_scope: Token lacks a required OAuth scopeThe token used is not granted the specific scope permissions required to…
Error oauth_authorization_url_mismatch - quick answers
What does Slack error oauth_authorization_url_mismatch mean?
You are finishing the install with oauth.v2.access , but the user started it on a different version of Slack's authorize page. The docs say "The OAuth flow was initiated on an incorrect version of the authorization url. The flow must be initiated via /oauth/v2/authorize." Slack's OAuth has two versions, and each step must match.
How do I fix Slack error oauth_authorization_url_mismatch?
1. Find every install link (site, docs, emails, app directory listing) and point it to https://slack.com/oauth/v2/authorize. 2. Pass bot scopes as scope and user scopes as user_scope in the v2 URL. 3. Generate the authorize URL in one place in code instead of hard-coding it in pages. 4. Have the user start the install again from the corrected link.
Stop debugging Slack by hand
Connect the channel through Conferbot: tokens, webhooks and retries are handled, failures show as readable status.