Sign in with Google

Your page ──▶ your backend: GET /v1/oauth/google/url?appId=…&redirectUrl=<callback>  ──▶ { url }
Browser ──▶ url (Google) ──▶ Identise callback ──302──▶ <callback>?connectionToken=…
Your backend: POST /v1/oauth/exchange { connectionToken }  (X-Api-Key) ──▶ { accessToken, refreshToken }

1. 1

   Get the Google address

   GET /v1/oauth/google/url?appId=<App ID>&redirectUrl=<URL-encoded callback> → { url }. The callback must be registered (or be a path under your homepage, such as /auth/callback). Redirect the browser to url.

2. 2

   Google, then back to you

   After Google, Identise creates the user in your app if needed and redirects to your callback with ?connectionToken=… added. Your own query parameters are kept: …/callback?next=/billing&connectionToken=….

3. 3

   Exchange the token from your backend

   POST /v1/oauth/exchange { connectionToken } with X-Api-Key → tokens. The token is single-use and expires after 5 minutes; a second exchange answers 401.

   ts

   // GET /auth/identise/callback
   const url = new URL(request.url);
   const mfaToken = url.searchParams.get("mfaToken");
   if (mfaToken) return askForCode(mfaToken); // see "If the user has two-factor on"
   
   const connectionToken = url.searchParams.get("connectionToken");
   const tokens = await identise<{ accessToken: string; refreshToken: string }>("/v1/oauth/exchange", { connectionToken });

If the user has two-factor on

The callback gets ?mfaToken=… instead of a connection token. Ask for their 6-digit code and finish with POST /v1/oauth/verify-mfa { appId, mfaToken, mfaCode } → tokens, exactly as after a password (see Two-factor authentication). So your callback should look for both parameters.

When Identise refuses