Skip to content
IntelliAuth

Callback URL

The callback URL is where IntelliAuth sends the user back after a successful sign-in. It's technically one of the redirect URIs you register on the application — usually the first, usually the one your developers point at first.

What's on the other end

Section titled “What's on the other end”

When the user clicks "Sign in" in your application, the browser is redirected to IntelliAuth. The user signs in. IntelliAuth redirects them to the callback URL with an ?code=...&state=... query string.

The page at the callback URL is responsible for:

  1. Reading the code and state from the query string.
  2. Validating state matches what your app stored before the redirect (CSRF defence).
  3. Exchanging the code for tokens by calling /oauth2/token on the tenant.
  4. Storing the tokens (usually via the SDK).
  5. Redirecting the user to wherever they were trying to go.

This is what the SDKs do for you. If you're using @intelliauth/react-sdk, the SDK handles steps 1-4; you just need a route in your app that the SDK can hook into.

Typical shape

Section titled “Typical shape”

For a SPA, the callback URL is a route in your app:

https://app.cymmetri.com/callback

The page at /callback is typically a thin component that renders a loading state, lets the SDK do its work, then navigates to the dashboard. The React SDK ships an <IntelliAuthCallback /> component you can drop in.

For a server-side app, the callback URL is a route on your backend:

https://app.cymmetri.com/auth/callback

The backend route receives the code, exchanges it for tokens server-side, sets a session cookie, redirects to the app's home.

For a native app, the callback is a custom-scheme URI:

com.cymmetri.banking://callback

The OS routes the redirect back to the native app via the registered scheme.

Register it

Section titled “Register it”

The callback URL is just one redirect URI; register it on the application's Settings tab under Redirect URIs. See Redirect URIs for the full discussion of how matching works, wildcards, multiple environments, etc.

When to add more than one

Section titled “When to add more than one”

A real production app usually has more than one callback registered:

  • Production — https://app.cymmetri.com/callback
  • Staging — https://staging.cymmetri.com/callback
  • Local dev — http://localhost:5173/callback
  • Local dev on a different port — http://localhost:3000/callback

All on the same application, all in the URLs tab. The browser tells IntelliAuth which one it's using on the /oauth2/authorize call; IntelliAuth checks it against the registered list.

Per the OAuth best-current-practice guidance, keeping environments on separate applications is cleaner — see Redirect URIs for the trade-offs.

What it's not

Section titled “What it&#39;s not”
  • Not the sign-in URL. That's /oauth2/authorize on the tenant, and your app sends users there, not the other way around.
  • Not the logout URL. That's a separate concept; see the Redirect URIs section in the application's Settings tab for the logout-return field.
  • Not the homepage. The callback is a specific code-exchange route, not your app's /. Putting the callback handler at / works but is unusual; you'd have to special-case the ?code= parameter.