linear oauth failed redirect_uri not whitelisted error

linear oauth failed redirect_uri not whitelisted error

TL;DR

Linear enforces exact redirect URI matching, so copy the exact redirect_uri your app sends and add it verbatim in the Linear app's OAuth redirect URI list. Watch the scheme, host, path, and trailing slash. Retry the authorize flow and the code exchange should proceed.

linear oauth failed redirect_uri not whitelisted error

Use this when

• Linear OAuth authorize step fails mentioning redirect_uri
• The integration works locally but fails when deployed
• A recent URL change (domain, path, or HTTPS) preceded the failure

Not for this skill when

• Token endpoint errors after a successful authorize (different stage)
• invalid_scope errors (scope problem, not redirect)
• User denies the consent screen (user choice, not config)

Steps

Step 1: Capture the exact redirect URI

Log or copy the redirect_uri parameter your app actually sends in the authorize URL. Expected: you have the literal string, not what you think it sends.

Step 2: Register it verbatim in Linear

In the Linear app settings under OAuth, add that exact URI to the redirect URI list. Expected: the list contains the URI character for character.

Step 3: Fix scheme and host issues

Use https in production, include any port or path the app really uses, and drop query strings unless Linear supports them. Expected: the registered URI matches the request on every component.

Step 4: Retry the authorize flow

Start the OAuth flow again from the beginning. Expected: Linear redirects back to your callback with a code instead of an error.

Step 5: Confirm the full exchange

Exchange the code for tokens and make a test API call. Expected: tokens are issued and the API responds.

Step 6: Register all environments

Add the redirect URIs for local, staging, and production so each environment works. Expected: no environment is left failing.

Tool compatibility

Linear OAuth 2.0 apps; Linear app settings (OAuth redirect URIs); the integrating application's auth callback route.

Variant phrasings

Variant 1

linear oauth redirect_uri mismatch not whitelisted

Variant 2

linear oauth error redirect uri is not registered

Variant 3

linear app oauth callback url invalid

Why it happens

The redirect URI check exists so stolen authorization codes cannot be delivered to an attacker's address: the provider only sends codes to pre-registered destinations. Linear applies the check strictly, comparing the sent value against the registered list. The mismatch is usually mundane, a trailing slash, http vs https, or a deploy that changed the domain, but the error gives no hint which character differs, so the fix is mechanical comparison. Local development adds a wrinkle because the registered local URI and the deployed URI are different entries that must both exist.

Edge cases / pitfalls

• Some providers allow query strings in redirect URIs and some do not; keep the registered URI clean and pass state via the state parameter.
• Reverse proxies that terminate TLS can make the app generate an http redirect_uri behind an https URL; configure the proxy headers.
• Do not register overly broad redirect URIs to dodge the check; that defeats the security control.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kG47sl1wetXY4SlOiDMqIQ