Verify users

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.

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

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

Pass these fields when creating the authorization link:

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,
)

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,
});

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.

# 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

// 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.