Prerequisites
- A Scalekit account and environment
- Admin access to configure applications in Scalekit
- Access to the Char dashboard
Quick Links
Scalekit Dashboard
Sign in to your Scalekit Dashboard
FSA Quickstart
Full Stack Auth Quickstart Guide
Token Management
Session and token management docs
Code Samples
Full Stack Auth code examples
SDK References
@scalekit-sdk/node
Scalekit Node.js SDK
scalekit-sdk-python
Scalekit Python SDK
scalekit-sdk-go
Scalekit Go SDK
Configuration Steps
Create a Scalekit Environment
- Sign in to the Scalekit Dashboard
- Create a new environment (e.g.,
stagingorproduction) - Note your environment details:
| Value | Example |
|---|---|
| Environment URL | https://your-app.scalekit.com |
| Client ID | skc_58327482062864390 |
| Client Secret | sks_... (keep secure) |
Configure Redirect URLs
In your Scalekit Dashboard, navigate to Authentication → Redirect URLs and add:
| Setting | Value |
|---|---|
| Allowed Callback URL | Your application’s callback URL (e.g., https://app.example.com/callback) |
| Initiate-login URL | Your application’s login initiation URL |
| Post-logout URL | Where users should land after logout |
Configure Authentication Methods
In Authentication → Auth Methods, enable the login methods you want:
- Email/Password
- Magic Link / Email OTP
- Social logins (Google, Microsoft, GitHub, etc.)
- Enterprise SSO (SAML/OIDC)
Configure Char
In the Char Dashboard:
- Navigate to Settings → Integration
- Under SSO Configuration, select Custom OIDC as the provider
- Enter your Issuer URL (your Scalekit environment URL, e.g.,
https://your-app.scalekit.com) - Enter your Client ID (e.g.,
skc_58327482062864390) - Click Test Connection to verify
- Click Save Changes
Configuration Reference
| Char Field | Scalekit Value | Example |
|---|---|---|
| Provider Type | Custom OIDC | oidc |
| Issuer URL | Environment URL | https://your-app.scalekit.com |
| Client ID | Application Client ID | skc_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:| Claim | Requirement |
|---|---|
iss | Must match your Scalekit environment URL |
aud | Must include your configured Client ID |
sub | Required - used as the user identifier (e.g., usr_63261014140912135) |
exp | Must not be expired |
Scalekit ID Token Claims
Scalekit ID tokens include these standard claims:| Claim | Description |
|---|---|
sub | Unique user identifier |
oid | Organization ID (if user belongs to an organization) |
sid | Session ID |
email | User’s email address |
email_verified | Whether email has been verified |
Example: Obtaining and Passing the Token
- Node.js SDK
- React
- Next.js (SSR with Ticket)
- Express.js Callback
Building the Authorization URL
To initiate login, redirect users to Scalekit’s authorization endpoint: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_accountwithorganization_idparameter - Roles: Available in access tokens as
roles[]array
Troubleshooting
INVALID_ISSUER error
INVALID_ISSUER error
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)
INVALID_AUDIENCE error
INVALID_AUDIENCE error
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
JWKS_FETCH_FAILED error
JWKS_FETCH_FAILED error
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
Token refresh issues
Token refresh issues
If tokens aren’t refreshing correctly:
- Ensure
offline_accessscope 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:| Feature | Description |
|---|---|
| Enterprise SSO | Built-in SAML and OIDC support for enterprise customers |
| Directory Sync (SCIM) | Automatic user provisioning from identity directories |
| MCP Auth | Native OAuth 2.1 support for MCP servers |
| Agent Auth | Authentication for AI agents with 40+ OAuth providers |
| Admin Portal | Self-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
SecureandSameSite=Strictflags - 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

