Verify user identity

User verification applies to OAuth-based connectors only. For API key, basic auth, and key pair connectors, the user provides credentials directly. No OAuth flow, no verification step needed.

For OAuth connectors, user verification confirms that the user who completed the OAuth consent is the same user your app intended to connect, before Scalekit activates the connected account. It stops an authorization link from activating the wrong account, for example when a link is forwarded or phished.

Choose a mode in AgentKit > Settings > User Verification:

• Custom user verifier (recommended): your server confirms that the authorizing user matches the user your app intended to connect. Use it in production.
• Scalekit users only: Scalekit checks that the authorizing user is invited to your Scalekit workspace and signed in to the dashboard. No code required. Use it for development and testing, when every user is on your team.
• None: no verification. The connected account activates as soon as OAuth completes, so anyone who opens an authorization link can activate it.

New environments start with None, because your agent may run somewhere that can’t confirm which user is signed in. Switch to Custom user verifier before you onboard real users.

Scalekit users only is for testing

In this mode, the user authorizing the connection must already be signed in to the Scalekit dashboard. No verify route or API calls are needed in your code. Switch to Custom user verifier before onboarding real users.

With Custom user verifier, your application implements the verify step. End users never interact with Scalekit directly.

When the user finishes OAuth, Scalekit redirects to your verify URL with auth_request_id and state params. Your route reads the user from your session, calls Scalekit’s verify API with the auth_request_id and the original identifier, and if they match, the connected account activates.

Review the verification sequence

Implement verification in your app

If you haven’t installed the SDK yet, see the quickstart.

Generate the authorization link

Pass these fields when creating the authorization link:

Field	Description
identifier	Required. Your user’s ID in your system, such as user_123. Use an opaque value that only your system maps to a user, not an email address: anyone with your client secret can call tools as any identifier, so a guessable one is easier to misuse. Scalekit stores it and checks that the verify call sends the same value.
user_verify_url	Required. Your callback URL; Scalekit redirects the user here after OAuth completes.
state	Recommended. A random value to prevent CSRF.

How to use state

Generate a cryptographically random value per flow, store it in a secure HTTP-only cookie, and validate it against the state query param on callback. Discard the request if they don’t match; this prevents an attacker from sending crafted verify URLs to your users.

Python

import secrets

# Generate a state value to prevent CSRF
state = secrets.token_urlsafe(32)
# Store state in a secure, HTTP-only cookie to validate on callback

response = scalekit_client.actions.get_authorization_link(
    connection_name=connector,
    identifier=user_id,
    user_verify_url="https://app.yourapp.com/user/verify",
    state=state,
)

Node.js

import crypto from 'node:crypto';

// Generate a state value to prevent CSRF
const state = crypto.randomUUID();
// Store state in a secure, HTTP-only cookie to validate on callback

const { link } = await scalekit.actions.getAuthorizationLink({
  identifier: userId,
  connectionName: connector,
  userVerifyUrl: 'https://app.yourapp.com/user/verify',
  state,
});

Handle the verification callback

After OAuth completes, Scalekit redirects to your user_verify_url:

GET https://app.yourapp.com/user/verify?auth_request_id=req_xyz&state=<your_state>

Validate state against your cookie, then call Scalekit’s verify endpoint server-side.

Never trust query params for identity

Read the user’s identity from your own session, not from the URL. Use state for session correlation only.

Python

# 1. Validate state from query param matches state in cookie
# 2. Read user identity from your session, not from the URL

response = scalekit_client.actions.verify_connected_account_user(
    auth_request_id=auth_request_id,
    identifier=user_id,    # must match what was stored at link creation
)
# On success: redirect to response.post_user_verify_redirect_url

Node.js

// 1. Validate state from query param matches state in cookie
// 2. Read user identity from your session, not from the URL

const { postUserVerifyRedirectUrl } =
  await scalekit.actions.verifyConnectedAccountUser({
    authRequestId: auth_request_id,
    identifier: userId,     // must match what was stored at link creation
  });
// On success: redirect to postUserVerifyRedirectUrl

On success, the connected account is activated. Redirect the user using post_user_verify_redirect_url.

Common scenarios

Why does authorization fail when no verification redirect URL is configured?

The authorization flow fails with a failed_to_exchange error (user_verify_url not configured for verification redirect) when the environment is set to Custom user verifier, but the flow started without a user_verify_url. Scalekit completes the OAuth exchange but has nowhere to redirect the user for verification.

Resolve it in one of two ways:

• In production, pass user_verify_url when you generate the authorization link, and implement the verification callback at that URL.
• In development or internal testing, set the mode to Scalekit users only in AgentKit > Settings > User Verification. This mode needs no user_verify_url and no verify route, as long as every authorizing user is signed in to your Scalekit dashboard.