Skip to main content
Connect Scalekit to authenticate end users with your Char agent. Configure your Scalekit environment and set up Char for token validation.

Prerequisites

  • A Scalekit account and environment
  • Admin access to configure applications in Scalekit
  • Access to the Char dashboard

SDK References

Configuration Steps

1

Create a Scalekit Environment

  1. Sign in to the Scalekit Dashboard
  2. Create a new environment (e.g., staging or production)
  3. Note your environment details:
ValueExample
Environment URLhttps://your-app.scalekit.com
Client IDskc_58327482062864390
Client Secretsks_... (keep secure)
2

Configure Redirect URLs

In your Scalekit Dashboard, navigate to AuthenticationRedirect URLs and add:
SettingValue
Allowed Callback URLYour application’s callback URL (e.g., https://app.example.com/callback)
Initiate-login URLYour application’s login initiation URL
Post-logout URLWhere users should land after logout
3

Configure Authentication Methods

In AuthenticationAuth Methods, enable the login methods you want:
  • Email/Password
  • Magic Link / Email OTP
  • Social logins (Google, Microsoft, GitHub, etc.)
  • Enterprise SSO (SAML/OIDC)
4

Configure Char

In the Char Dashboard:
  1. Navigate to SettingsIntegration
  2. Under SSO Configuration, select Custom OIDC as the provider
  3. Enter your Issuer URL (your Scalekit environment URL, e.g., https://your-app.scalekit.com)
  4. Enter your Client ID (e.g., skc_58327482062864390)
  5. Click Test Connection to verify
  6. Click Save Changes

Configuration Reference

Char FieldScalekit ValueExample
Provider TypeCustom OIDCoidc
Issuer URLEnvironment URLhttps://your-app.scalekit.com
Client IDApplication Client IDskc_58327482062864390
Scalekit uses your environment URL as the issuer. The JWKS endpoint is at {environment_url}/.well-known/jwks.json and the discovery document is at {environment_url}/.well-known/openid-configuration.

Token Requirements

Char validates Scalekit ID tokens with these requirements:
ClaimRequirement
issMust match your Scalekit environment URL
audMust include your configured Client ID
subRequired - used as the user identifier (e.g., usr_63261014140912135)
expMust not be expired

Scalekit ID Token Claims

Scalekit ID tokens include these standard claims:
{
  "sub": "usr_63261014140912135",
  "email": "[email protected]",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "oid": "org_59615193906282635",
  "sid": "ses_65274187031249433",
  "aud": ["skc_58327482062864390"],
  "iss": "https://your-app.scalekit.com",
  "exp": 1742975822,
  "iat": 1742974022
}
ClaimDescription
subUnique user identifier
oidOrganization ID (if user belongs to an organization)
sidSession ID
emailUser’s email address
email_verifiedWhether email has been verified

Example: Obtaining and Passing the Token

import { ScalekitClient } from '@scalekit-sdk/node';
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

// Server-side: Exchange code for tokens after OAuth callback
const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENVIRONMENT_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);

const CLIENT_ID = "your-scalekit-client-id";

// In your callback handler
const result = await scalekit.authenticateWithCode(code, redirectUri);
const idToken = result.idToken;

// Client-side: Pass the ID token to the agent
const agent = document.querySelector("char-agent") as WebMCPAgentElement
  ?? document.createElement("char-agent") as WebMCPAgentElement;

if (!agent.isConnected) {
  document.body.appendChild(agent);
}

// Use connect() - keeps token out of DOM
agent.connect({ idToken, clientId: CLIENT_ID });
Which approach? Use SSR with Ticket if you want to keep Scalekit JWTs server-side (more secure). Use the SDK directly if you need the JWT client-side for other purposes.

Building the Authorization URL

To initiate login, redirect users to Scalekit’s authorization endpoint:
const authUrl = new URL(`${SCALEKIT_ENVIRONMENT_URL}/oauth/authorize`);
authUrl.searchParams.set('client_id', SCALEKIT_CLIENT_ID);
authUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid profile email');

// Optional: Pre-select an organization
authUrl.searchParams.set('organization_id', 'org_...');

window.location.href = authUrl.toString();

Organizations and Multi-Tenancy

Scalekit supports multi-tenant applications with organizations:
  • Organization ID (oid): Present in tokens when user belongs to an organization
  • Organization Switching: Use prompt=select_account with organization_id parameter
  • Roles: Available in access tokens as roles[] array
// Switch organization
const authUrl = new URL(`${SCALEKIT_ENVIRONMENT_URL}/oauth/authorize`);
authUrl.searchParams.set('client_id', SCALEKIT_CLIENT_ID);
authUrl.searchParams.set('redirect_uri', redirectUri);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('organization_id', targetOrgId);
authUrl.searchParams.set('prompt', 'select_account');

Troubleshooting

The token issuer doesn’t match your configured environment URL:
  • Verify the Issuer URL in Char matches your Scalekit environment URL exactly
  • Ensure you’re using the full URL including https://
  • Check that you’re using the correct environment (staging vs production)
The token’s aud claim doesn’t match your configured Client ID:
  • Ensure the Client ID matches your Scalekit application exactly (e.g., skc_...)
  • Verify you’re using the ID token, not the access token
  • Check that you’re using the correct environment’s credentials
Char couldn’t reach Scalekit’s JWKS endpoint:
  • Verify your environment URL is correct
  • Check that your Scalekit environment is active
  • Use Test Connection in the dashboard to verify
If tokens aren’t refreshing correctly:
  • Ensure offline_access scope is included in authorization request
  • Check that refresh tokens are stored securely server-side
  • Verify your client secret is correct for the token refresh call

Scalekit Features

Scalekit offers additional features that complement Char integration:
FeatureDescription
Enterprise SSOBuilt-in SAML and OIDC support for enterprise customers
Directory Sync (SCIM)Automatic user provisioning from identity directories
MCP AuthNative OAuth 2.1 support for MCP servers
Agent AuthAuthentication for AI agents with 40+ OAuth providers
Admin PortalSelf-service SSO configuration for your customers

Scalekit Documentation

Explore the full Scalekit documentation

Security Best Practices

  • Store refresh tokens server-side in encrypted storage, never client-side
  • Use HttpOnly cookies for session tokens with Secure and SameSite=Strict flags
  • Enable MFA in Scalekit for enhanced security
  • Use short-lived access tokens (Scalekit default is 5 minutes)
  • Implement token refresh to avoid session interruptions
  • Monitor auth logs in the Scalekit dashboard for suspicious activity