Connect GitHub before summarizing pull requests.
`;
17
const authButtonLabel = connected ? "Reconnect GitHub" : "Connect GitHub";
18
19
return `
20
21
22
${connectedBanner}
23
{
4
sub: string
5
email: string
6
email_verified: boolean
7
name: string
8
given_name: string
9
family_name: string
10
picture: string
11
oid: string // organization_id
12
}
13
14
export default function Scalekit(
15
options: OAuthUserConfig
& {
16
issuer: string
17
organizationId?: string
18
connectionId?: string
19
domain?: string
20
}
21
): OAuthConfig
{
22
const { issuer, organizationId, connectionId, domain } = options
23
24
return {
25
id: "scalekit",
26
name: "Scalekit",
27
type: "oidc",
28
issuer,
29
authorization: {
30
params: {
31
scope: "openid email profile",
32
...(connectionId && { connection_id: connectionId }),
33
...(organizationId && { organization_id: organizationId }),
34
...(domain && { domain }),
35
},
36
},
37
profile(profile) {
38
return {
39
id: profile.sub,
40
name: profile.name ?? `${profile.given_name} ${profile.family_name}`,
41
email: profile.email,
42
image: profile.picture ?? null,
43
}
44
},
45
style: { bg: "#6f42c1", text: "#fff" },
46
options,
47
}
48
}
```
After PR #13392 merges, replace the local import with:
```typescript
1
import Scalekit from "next-auth/providers/scalekit"
```
### 4. Configure `auth.ts`
[Section titled “4. Configure auth.ts”](#4-configure-authts)
Create `auth.ts` in your project root:
```typescript
1
import NextAuth from "next-auth"
2
import Scalekit from "./providers/scalekit" // → "next-auth/providers/scalekit" after PR #13392
3
4
export const { handlers, auth, signIn, signOut } = NextAuth({
5
providers: [
6
Scalekit({
7
issuer: process.env.AUTH_SCALEKIT_ISSUER!,
8
clientId: process.env.AUTH_SCALEKIT_ID!,
9
clientSecret: process.env.AUTH_SCALEKIT_SECRET!,
10
// Routing: set one of these (see step 7 for strategy)
11
connectionId: process.env.AUTH_SCALEKIT_CONNECTION_ID,
12
}),
13
],
14
basePath: "/auth",
15
session: { strategy: "jwt" },
16
})
```
`basePath: "/auth"` is required to match the redirect URI you registered in step 1. Without it, Auth.js uses `/api/auth` and the Scalekit callback will fail.
### 5. Set environment variables
[Section titled “5. Set environment variables”](#5-set-environment-variables)
.env.local
```bash
1
# Generate with: npx auth secret
2
AUTH_SECRET=
3
4
# From Scalekit dashboard → API Keys
5
AUTH_SCALEKIT_ISSUER=https://yourenv.scalekit.dev
6
AUTH_SCALEKIT_ID=skc_...
7
AUTH_SCALEKIT_SECRET=
8
9
# Connection ID for development routing (conn_...)
10
# In production, resolve this dynamically per tenant — see step 7
11
AUTH_SCALEKIT_CONNECTION_ID=conn_...
```
`AUTH_SECRET` is not optional. Auth.js uses it to sign JWTs and encrypt session cookies. Missing it causes sign-in to fail silently.
### 6. Wire up route handlers
[Section titled “6. Wire up route handlers”](#6-wire-up-route-handlers)
Create `app/auth/[...nextauth]/route.ts`:
```typescript
1
import { handlers } from "@/auth"
2
export const { GET, POST } = handlers
```
This exposes `GET /auth/callback/scalekit` and `POST /auth/signout` — the endpoints Auth.js needs. The directory must be `app/auth/` (not `app/api/auth/`) to match the `basePath` you configured.
### 7. SSO routing strategies
[Section titled “7. SSO routing strategies”](#7-sso-routing-strategies)
Scalekit resolves which IdP connection to activate using these params (highest to lowest precedence):
```typescript
1
Scalekit({
2
issuer: process.env.AUTH_SCALEKIT_ISSUER!,
3
clientId: process.env.AUTH_SCALEKIT_ID!,
4
clientSecret: process.env.AUTH_SCALEKIT_SECRET!,
5
6
// Option A — exact connection (dev / single-tenant use)
7
connectionId: "conn_...",
8
9
// Option B — org's active connection (multi-tenant: look up org from user's DB record)
10
organizationId: "org_...",
11
12
// Option C — resolve org from email domain (useful at login prompt)
13
domain: "acme.com",
14
})
```
In production, don’t hardcode these values. Store `organizationId` or `connectionId` per tenant in your database, then construct the `signIn()` call dynamically based on the authenticated user’s org:
```typescript
1
// Example: look up org at sign-in time
2
const org = await db.organizations.findByDomain(emailDomain)
3
4
await signIn("scalekit", {
5
organizationId: org.scalekitOrgId,
6
redirectTo: "/dashboard",
7
})
```
### 8. Trigger sign-in and read the session
[Section titled “8. Trigger sign-in and read the session”](#8-trigger-sign-in-and-read-the-session)
A server component reads the session, and a sign-in form triggers the flow:
app/page.tsx
```typescript
1
import { auth, signIn } from "@/auth"
2
3
export default async function Home() {
4
const session = await auth()
5
6
if (session) {
7
return (
8
9
Signed in as {session.user?.email}
10
Welcome, {session.email}
;
9
}
```
For a coarse, fast gate across many routes, add middleware that only checks whether a session cookie exists. Keep real validation in the page or Route Handler.
middleware.ts
```ts
1
import { NextRequest, NextResponse } from 'next/server';
2
3
export function middleware(request: NextRequest) {
4
// Presence check only — middleware runs on the Edge runtime and cannot call the
5
// Scalekit SDK. getSession() does the cryptographic validation downstream.
6
const hasSession = request.cookies.has('sk_access_token');
7
if (!hasSession) {
8
return NextResponse.redirect(new URL('/login', request.url));
9
}
10
return NextResponse.next();
11
}
12
13
export const config = { matcher: ['/dashboard/:path*'] };
```
## Sign out
[Section titled “Sign out”](#sign-out)
Build the Scalekit logout URL, clear your cookies, and redirect the browser to Scalekit so the server-side session ends too. Pass the ID token as `idTokenHint` before you clear it.
app/logout/route.ts
```ts
1
import { cookies } from 'next/headers';
2
import { NextResponse } from 'next/server';
3
import { scalekit } from '@/lib/scalekit';
4
5
export async function GET() {
6
const cookieStore = await cookies();
7
const idToken = cookieStore.get('sk_id_token')?.value;
8
9
const logoutUrl = scalekit.getLogoutUrl({
10
idTokenHint: idToken,
11
postLogoutRedirectUri: 'http://localhost:3000/login',
12
});
13
14
const response = NextResponse.redirect(logoutUrl);
15
// Clear local cookies after building the logout URL, so the ID token is still
16
// available to tell Scalekit which session to end.
17
response.cookies.delete('sk_access_token');
18
response.cookies.delete('sk_id_token');
19
response.cookies.delete('sk_refresh_token');
20
return response;
21
}
```
Logout must be a browser redirect
Redirect the browser to the logout URL rather than calling it from server code. The redirect carries Scalekit’s session cookie, which lets Scalekit identify and end the correct session.
## Verify it works
[Section titled “Verify it works”](#verify-it-works)
1. Start the app with `pnpm dev` and open `http://localhost:3000/dashboard`. The middleware redirects you to `/login`.
2. Visit `http://localhost:3000/login`. The browser lands on Scalekit’s hosted login page showing every method you enabled in the dashboard.
3. Sign in. Scalekit returns to `/api/callback`, which sets the session cookies and forwards you to `/dashboard`, where your email renders.
4. Inspect cookies in your browser devtools. Confirm `sk_access_token`, `sk_id_token`, and `sk_refresh_token` are present and marked `HttpOnly`.
5. Open `http://localhost:3000/logout`. Your cookies clear, Scalekit ends the session, and you return to `/login`.
## Production notes
[Section titled “Production notes”](#production-notes)
* **Encrypt cookie values.** This recipe stores raw tokens for clarity. In production, encrypt them with `SESSION_COOKIE_SECRET` (for example with [`jose`](https://github.com/panva/jose)) before writing, and decrypt on read.
* **Drive refresh from the client.** Call `POST /api/refresh` from a client effect shortly before the access token expires, or retry once on a `401`, so sessions renew without a full re-login.
* **Use absolute redirect URLs per environment.** Replace the hard-coded `localhost` URLs with an environment variable, and register each environment’s callback and post-logout URLs in the dashboard.
When you are ready to ship, walk the [production readiness checklist](/authenticate/launch-checklist/). To inspect what the access token carries, see [ID token claims](/guides/idtoken-claims/).
---
# DOCUMENT BOUNDARY
---
# Building a Custom Organization Switcher
> Learn how to build your own organization switcher UI for complete control over multi-tenant user experiences.
When users belong to multiple organizations, the default Scalekit organization switcher handles most use cases. However, some applications require deeper integration—a custom switcher embedded directly in your app’s navigation, or a specialized UI that matches your design system.
This guide shows you how to build your own organization switcher using Scalekit’s APIs.
## Why build a custom switcher?
[Section titled “Why build a custom switcher?”](#why-build-a-custom-switcher)
The default Scalekit-hosted switcher works well for most scenarios. Build a custom switcher when you need:
* **In-app navigation**: Users switch organizations without leaving your application
* **Custom branding**: The switcher matches your application’s design language
* **Specialized workflows**: Your app needs org-specific logic during switches
* **Reduced redirects**: Avoid sending users through the authentication flow for every switch
## How the custom switcher works
[Section titled “How the custom switcher works”](#how-the-custom-switcher-works)
Your application handles the entire switching flow:
1. User authenticates through Scalekit and receives a session
2. Your app fetches the user’s organizations via the User Sessions API
3. You render your own organization selector UI
4. When a user selects an organization, your app updates the active context
This approach gives you full control over the UI and routing, but requires you to manage session state and organization context within your application.
## Fetch user organizations
[Section titled “Fetch user organizations”](#fetch-user-organizations)
The User Sessions API returns the `authenticated_organizations` field containing all organizations the user can access. Use this data to populate your switcher UI.
* Node.js
Express.js
```javascript
1
// Use case: Get user's organizations for your switcher UI
2
// Security: Always validate session ownership before returning org data
3
const session = await scalekit.session.getSession(sessionId);
4
5
// Extract organizations from the session response
6
const organizations = session.authenticated_organizations || [];
7
8
// Render your organization switcher with this data
9
res.json({ organizations });
```
* Python
Flask
```python
1
# Use case: Get user's organizations for your switcher UI
2
# Security: Always validate session ownership before returning org data
3
session = scalekit_client.sessions.get_session(session_id)
4
5
# Extract organizations from the session response
6
organizations = session.get('authenticated_organizations', [])
7
8
# Render your organization switcher with this data
9
return jsonify({'organizations': organizations})
```
* Go
Gin
```go
1
// Use case: Get user's organizations for your switcher UI
2
// Security: Always validate session ownership before returning org data
3
session, err := scalekitClient.Session().GetSession(ctx, sessionId)
4
if err != nil {
5
return err
6
}
7
8
// Extract organizations from the session response
9
organizations := session.AuthenticatedOrganizations
10
11
// Render your organization switcher with this data
12
c.JSON(http.StatusOK, gin.H{"organizations": organizations})
```
* Java
Spring
```java
1
// Use case: Get user's organizations for your switcher UI
2
// Security: Always validate session ownership before returning org data
3
Session session = scalekitClient.sessions().getSession(sessionId);
4
5
// Extract organizations from the session response
6
List organizations = session.getAuthenticatedOrganizations();
7
8
// Render your organization switcher with this data
9
return ResponseEntity.ok(Map.of("organizations", organizations));
```
The response includes organization IDs, names, and metadata for each organization the user can access.
## Add domain context
[Section titled “Add domain context”](#add-domain-context)
Enhance your switcher by displaying which domains are associated with each organization. Use the Domains API to fetch this information.
```javascript
1
// Example: Fetch domains for an organization
2
const domains = await scalekit.domain.listDomains('org_123');
3
4
// Display "@acme.com" next to the organization name in your UI
```
This helps users quickly identify the correct organization, especially when they belong to organizations with similar names.
## Handle organization selection
[Section titled “Handle organization selection”](#handle-organization-selection)
When a user selects an organization in your custom switcher, update your application’s context. Store the active organization ID in session storage or a cookie, then use it for subsequent API calls.
* Node.js
Express.js
```javascript
1
// Use case: Store selected organization and fetch org-specific data
2
app.post('/api/select-organization', async (req, res) => {
3
const { organizationId } = req.body;
4
const sessionId = req.session.scalekitSessionId;
5
6
// Security: Verify the user belongs to this organization
7
const session = await scalekit.session.getSession(sessionId);
8
const hasAccess = session.authenticated_organizations.some(
9
org => org.id === organizationId
10
);
11
12
if (!hasAccess) {
13
return res.status(403).json({ error: 'Unauthorized' });
14
}
15
16
// Store the active organization in the user's session
17
req.session.activeOrganizationId = organizationId;
18
19
res.json({ success: true });
20
});
```
* Python
Flask
```python
1
# Use case: Store selected organization and fetch org-specific data
2
@app.route('/api/select-organization', methods=['POST'])
3
def select_organization():
4
data = request.get_json()
5
organization_id = data.get('organizationId')
6
session_id = session.get('scalekit_session_id')
7
8
# Security: Verify the user belongs to this organization
9
user_session = scalekit_client.sessions.get_session(session_id)
10
has_access = any(
11
org['id'] == organization_id
12
for org in user_session.get('authenticated_organizations', [])
13
)
14
15
if not has_access:
16
return jsonify({'error': 'Unauthorized'}), 403
17
18
# Store the active organization in the user's session
19
session['active_organization_id'] = organization_id
20
21
return jsonify({'success': True})
```
* Go
Gin
```go
1
// Use case: Store selected organization and fetch org-specific data
2
func SelectOrganization(c *gin.Context) {
3
var req struct {
4
OrganizationID string `json:"organizationId"`
5
}
6
if err := c.BindJSON(&req); err != nil {
7
c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request"})
8
return
9
}
10
11
sessionID := c.GetString("scalekitSessionID")
12
13
// Security: Verify the user belongs to this organization
14
session, err := scalekitClient.Session().GetSession(ctx, sessionID)
15
if err != nil {
16
c.JSON(http.StatusInternalServerError, gin.H{"error": "Session error"})
17
return
18
}
19
20
hasAccess := false
21
for _, org := range session.AuthenticatedOrganizations {
22
if org.ID == req.OrganizationID {
23
hasAccess = true
24
break
25
}
26
}
27
28
if !hasAccess {
29
c.JSON(http.StatusForbidden, gin.H{"error": "Unauthorized"})
30
return
31
}
32
33
// Store the active organization in the user's session
34
c.SetCookie("activeOrganizationID", req.OrganizationID, 3600, "/", "", true, true)
35
36
c.JSON(http.StatusOK, gin.H{"success": true})
37
}
```
* Java
Spring
```java
1
// Use case: Store selected organization and fetch org-specific data
2
@PostMapping("/api/select-organization")
3
public ResponseEntity selectOrganization(
4
@RequestBody Map request,
5
HttpSession httpSession
6
) {
7
String organizationId = request.get("organizationId");
8
String sessionId = (String) httpSession.getAttribute("scalekitSessionId");
9
10
// Security: Verify the user belongs to this organization
11
Session session = scalekitClient.sessions().getSession(sessionId);
12
boolean hasAccess = session.getAuthenticatedOrganizations().stream()
13
.anyMatch(org -> org.getId().equals(organizationId));
14
15
if (!hasAccess) {
16
return ResponseEntity.status(HttpStatus.FORBIDDEN)
17
.body(Map.of("error", "Unauthorized"));
18
}
19
20
// Store the active organization in the user's session
21
httpSession.setAttribute("activeOrganizationId", organizationId);
22
23
return ResponseEntity.ok(Map.of("success", true));
24
}
```
Always verify that the user actually belongs to the organization they’re attempting to switch to. The `authenticated_organizations` array from the session is your source of truth for access control.
## When to use the hosted switcher instead
[Section titled “When to use the hosted switcher instead”](#when-to-use-the-hosted-switcher-instead)
The default Scalekit-hosted switcher is the right choice when:
* You want the quickest implementation with minimal code
* Your application doesn’t require in-app organization switching
* You’re okay with users navigating through the authentication flow to switch organizations
Build a custom switcher when user experience requirements demand deeper integration with your application’s UI and routing.
You may refer to our [Sample Org Swithcer ](https://github.com/scalekit-inc/Nextjs-Django-Org-Switcher-Example/tree/main)application to better understand how the API calls enable this custom org switcher that is embedded inside your application.
---
# DOCUMENT BOUNDARY
---
# Implement passwordless auth in Next.js 15
> Add magic link and OTP authentication to your Next.js application using Scalekit's headless API.
Next.js 15’s App Router expects authentication to be server-first: tokens generated on the server, verification happening in Route Handlers or Server Actions, and sessions stored in HttpOnly cookies. If you’re building passwordless authentication (magic links + OTP), traditional client-side SDKs won’t work properly with this model.
This cookbook shows you how to implement passwordless auth that works natively with Next.js 15’s architecture using Scalekit’s headless API.
## The problem
[Section titled “The problem”](#the-problem)
You want passwordless authentication in Next.js 15 but face these challenges:
* **Client-side SDKs break App Router patterns** - They expect browser-side token handling, which violates server-first principles
* **Vendor UIs don’t match your design** - Pre-built login pages force you to compromise on branding
* **DIY is complex** - Building secure token generation, email delivery, verification, and session management from scratch is a significant lift
* **Cross-device failures** - Magic links often break when users switch devices or email clients strip parameters
## Who needs this
[Section titled “Who needs this”](#who-needs-this)
This cookbook is for you if:
* ✅ You’re building a Next.js 15 application using App Router
* ✅ You want passwordless authentication (magic links, OTP, or both)
* ✅ You need full control over your login UI and email design
* ✅ You don’t want to migrate your existing user database
* ✅ You require server-side security for compliance
You **don’t** need this if:
* ❌ You’re happy with vendor-hosted login pages
* ❌ You’re using Next.js Pages Router (not App Router)
* ❌ You prefer traditional username/password authentication
## The solution
[Section titled “The solution”](#the-solution)
Scalekit’s passwordless API provides three server-side methods that integrate directly with Next.js 15’s architecture:
1. **`sendPasswordlessEmail()`** - Generates and sends magic link/OTP to user’s email
2. **`verifyPasswordlessEmail()`** - Validates the token/code and returns verified identity
3. **`resendPasswordlessEmail()`** - Issues a fresh credential if the first expires
All security logic stays server-side, works with Server Actions and Route Handlers, and integrates with Edge Middleware for route protection.
## Implementation
[Section titled “Implementation”](#implementation)
### 1. Configure Scalekit dashboard
[Section titled “1. Configure Scalekit dashboard”](#1-configure-scalekit-dashboard)
Enable passwordless authentication in your [Scalekit dashboard](https://app.scalekit.com/):
1. Navigate to **Authentication → Passwordless**
2. Select **Magic Link + Verification Code** for maximum reliability
3. Set **Expiry Period** (e.g., 600 seconds for 10-minute lifetime)
4. Enable **Enforce same browser origin** to prevent link hijacking
5. (Optional) Enable **Regenerate credentials on resend** to invalidate old links
### 2. Install dependencies and configure environment
[Section titled “2. Install dependencies and configure environment”](#2-install-dependencies-and-configure-environment)
```bash
1
npm install @scalekit-sdk/node jsonwebtoken
```
Create `.env.local`:
```bash
1
SCALEKIT_ENVIRONMENT_URL=env_xxxx
2
SCALEKIT_CLIENT_ID=skc_xxx
3
SCALEKIT_CLIENT_SECRET=your_secret
4
APP_URL=http://localhost:3000
5
JWT_SECRET=your_jwt_secret
```
### 3. Create session management utilities
[Section titled “3. Create session management utilities”](#3-create-session-management-utilities)
Create `lib/session-store.ts` to handle server-side session creation:
```typescript
1
import jwt from 'jsonwebtoken';
2
import { cookies } from 'next/headers';
3
4
const COOKIE = 'session';
5
const SECRET = process.env.JWT_SECRET!;
6
7
export function createSession(email: string) {
8
const token = jwt.sign({ email }, SECRET, { expiresIn: '7d' });
9
cookies().set(COOKIE, token, {
10
httpOnly: true,
11
secure: process.env.NODE_ENV === 'production',
12
sameSite: 'lax',
13
path: '/',
14
maxAge: 60 * 60 * 24 * 7,
15
});
16
}
17
18
export function readSessionEmail(): string | null {
19
const token = cookies().get(COOKIE)?.value;
20
if (!token) return null;
21
22
try {
23
const decoded = jwt.verify(token, SECRET) as { email: string };
24
return decoded.email;
25
} catch {
26
return null;
27
}
28
}
29
30
export function clearSession() {
31
cookies().delete(COOKIE);
32
}
```
### 4. Create send email endpoint
[Section titled “4. Create send email endpoint”](#4-create-send-email-endpoint)
Create `app/api/auth/send-passwordless/route.ts`:
```typescript
1
import Scalekit from '@scalekit-sdk/node';
2
import { NextRequest, NextResponse } from 'next/server';
3
4
const scalekit = new Scalekit(
5
process.env.SCALEKIT_ENVIRONMENT_URL!,
6
process.env.SCALEKIT_CLIENT_ID!,
7
process.env.SCALEKIT_CLIENT_SECRET!
8
);
9
10
export async function POST(req: NextRequest) {
11
const { email } = await req.json();
12
13
try {
14
const response = await scalekit.passwordless.sendPasswordlessEmail(email, {
15
template: 'SIGNIN',
16
expiresIn: 600, // 10 minutes
17
state: crypto.randomUUID(),
18
magiclinkAuthUri: `${process.env.APP_URL}/api/auth/verify`,
19
});
20
21
return NextResponse.json({
22
authRequestId: response.authRequestId,
23
expiresAt: response.expiresAt,
24
});
25
} catch (error) {
26
return NextResponse.json(
27
{ error: 'Failed to send email' },
28
{ status: 500 }
29
);
30
}
31
}
```
### 5. Create verification endpoint
[Section titled “5. Create verification endpoint”](#5-create-verification-endpoint)
Create `app/api/auth/verify/route.ts` with both GET (magic link) and POST (OTP) handlers:
```typescript
1
import Scalekit from '@scalekit-sdk/node';
2
import { NextRequest, NextResponse } from 'next/server';
3
import { createSession } from '@/lib/session-store';
4
5
const scalekit = new Scalekit(
6
process.env.SCALEKIT_ENVIRONMENT_URL!,
7
process.env.SCALEKIT_CLIENT_ID!,
8
process.env.SCALEKIT_CLIENT_SECRET!
9
);
10
11
// Magic link verification
12
export async function GET(req: NextRequest) {
13
const url = new URL(req.url);
14
const linkToken = url.searchParams.get('link_token');
15
const authRequestId = url.searchParams.get('auth_request_id') ?? undefined;
16
17
if (!linkToken) {
18
return NextResponse.redirect(
19
new URL('/login?error=missing_token', req.url)
20
);
21
}
22
23
try {
24
const verified = await scalekit.passwordless.verifyPasswordlessEmail(
25
{ linkToken },
26
authRequestId
27
);
28
29
createSession(verified.email);
30
return NextResponse.redirect(new URL('/dashboard', req.url));
31
} catch {
32
return NextResponse.redirect(
33
new URL('/login?error=verification_failed', req.url)
34
);
35
}
36
}
37
38
// OTP verification
39
export async function POST(req: NextRequest) {
40
const { code, authRequestId } = await req.json();
41
42
if (!code || !authRequestId) {
43
return NextResponse.json(
44
{ error: 'Missing required fields' },
45
{ status: 400 }
46
);
47
}
48
49
try {
50
const verified = await scalekit.passwordless.verifyPasswordlessEmail(
51
{ code },
52
authRequestId
53
);
54
55
createSession(verified.email);
56
return NextResponse.json({ success: true });
57
} catch {
58
return NextResponse.json(
59
{ error: 'Invalid or expired code' },
60
{ status: 400 }
61
);
62
}
63
}
```
### 6. Add resend endpoint
[Section titled “6. Add resend endpoint”](#6-add-resend-endpoint)
Create `app/api/auth/resend-passwordless/route.ts`:
```typescript
1
import Scalekit from '@scalekit-sdk/node';
2
import { NextRequest, NextResponse } from 'next/server';
3
4
const scalekit = new Scalekit(
5
process.env.SCALEKIT_ENVIRONMENT_URL!,
6
process.env.SCALEKIT_CLIENT_ID!,
7
process.env.SCALEKIT_CLIENT_SECRET!
8
);
9
10
export async function POST(req: NextRequest) {
11
const { authRequestId } = await req.json();
12
13
if (!authRequestId) {
14
return NextResponse.json(
15
{ error: 'Missing authRequestId' },
16
{ status: 400 }
17
);
18
}
19
20
try {
21
const response = await scalekit.passwordless.resendPasswordlessEmail(
22
authRequestId
23
);
24
25
return NextResponse.json({
26
authRequestId: response.authRequestId,
27
expiresAt: response.expiresAt,
28
});
29
} catch {
30
return NextResponse.json(
31
{ error: 'Resend failed' },
32
{ status: 400 }
33
);
34
}
35
}
```
### 7. Protect routes with middleware
[Section titled “7. Protect routes with middleware”](#7-protect-routes-with-middleware)
Create `middleware.ts` in your project root:
```typescript
1
import { NextRequest, NextResponse } from 'next/server';
2
3
export function middleware(req: NextRequest) {
4
const protectedPath = req.nextUrl.pathname.startsWith('/dashboard');
5
const hasSession = Boolean(req.cookies.get('session')?.value);
6
7
if (protectedPath && !hasSession) {
8
const url = new URL('/login', req.url);
9
url.searchParams.set('next', req.nextUrl.pathname);
10
return NextResponse.redirect(url);
11
}
12
13
return NextResponse.next();
14
}
15
16
export const config = {
17
matcher: ['/dashboard/:path*'],
18
};
```
### 8. Build login UI (example)
[Section titled “8. Build login UI (example)”](#8-build-login-ui-example)
Create `app/login/page.tsx`:
```typescript
1
'use client';
2
3
import { useState } from 'react';
4
import { useRouter } from 'next/navigation';
5
6
export default function LoginPage() {
7
const [email, setEmail] = useState('');
8
const [authRequestId, setAuthRequestId] = useState('');
9
const [showOtp, setShowOtp] = useState(false);
10
const [otp, setOtp] = useState('');
11
const router = useRouter();
12
13
async function handleSendEmail(e: React.FormEvent) {
14
e.preventDefault();
15
16
const res = await fetch('/api/auth/send-passwordless', {
17
method: 'POST',
18
headers: { 'Content-Type': 'application/json' },
19
body: JSON.stringify({ email }),
20
});
21
22
const data = await res.json();
23
setAuthRequestId(data.authRequestId);
24
setShowOtp(true);
25
}
26
27
async function handleVerifyOtp(e: React.FormEvent) {
28
e.preventDefault();
29
30
const res = await fetch('/api/auth/verify', {
31
method: 'POST',
32
headers: { 'Content-Type': 'application/json' },
33
body: JSON.stringify({ code: otp, authRequestId }),
34
});
35
36
if (res.ok) {
37
router.push('/dashboard');
38
}
39
}
40
41
return (
42
43
{!showOtp ? (
44
54
) : (
55
66
)}
67
Team Performance Report
87
Summary
88
Team Size: ${report.team_size}
89
Total Issues: ${report.issues.total}
90
Completed Issues: ${report.issues.completed}
91
In Progress: ${report.issues.in_progress}
92
${report.meetings ? `Total Meetings: ${report.meetings.total}
` : ''}
93
94
95
`;
96
97
// Send report via email
98
const emailResults = await Promise.all(
99
team_members.map(member =>
100
context.tools.execute({
101
tool: 'send_email',
102
parameters: {
103
to: [member],
104
subject: `Team Report - ${start_date} to ${end_date}`,
105
html_body: htmlReport
106
}
107
})
108
)
109
);
110
111
return {
112
report_url: 'Generated and sent via email',
113
summary: report,
114
sent_to: team_members.filter((_, index) => emailResults[index].status === 'sent')
115
};
116
}
117
};
```
## Registering custom tools
[Section titled “Registering custom tools”](#registering-custom-tools)
### Using the API
[Section titled “Using the API”](#using-the-api)
Register your custom tools with Agent Auth:
* JavaScript
```javascript
1
// Register a custom tool
2
const registeredTool = await agentConnect.tools.register({
3
...sendWelcomeEmail,
4
organization_id: 'your_org_id'
5
});
6
7
console.log('Tool registered:', registeredTool.id);
```
* Python
```python
1
# Register a custom tool
2
registered_tool = agent_connect.tools.register(
3
**send_welcome_email,
4
organization_id='your_org_id'
5
)
6
7
print(f'Tool registered: {registered_tool.id}')
```
* cURL
```bash
1
curl -X POST "${SCALEKIT_BASE_URL}/v1/connect/tools/custom" \
2
-H "Authorization: Bearer ${SCALEKIT_CLIENT_SECRET}" \
3
-H "Content-Type: application/json" \
4
-d '{
5
"name": "send_welcome_email",
6
"display_name": "Send Welcome Email",
7
"description": "Send a personalized welcome email to new users",
8
"category": "communication",
9
"provider": "custom",
10
"input_schema": {...},
11
"output_schema": {...},
12
"implementation": "async (parameters, context) => {...}"
13
}'
```
### Using the dashboard
[Section titled “Using the dashboard”](#using-the-dashboard)
1. In the [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Tools**
2. Click **Create Custom Tool**
3. Fill in the tool definition form
4. Test the tool with sample parameters
5. Save and activate the tool
## Tool context and utilities
[Section titled “Tool context and utilities”](#tool-context-and-utilities)
The `context` object provides access to:
### Standard tools
[Section titled “Standard tools”](#standard-tools)
Execute any standard Agent Auth tool:
```javascript
1
// Execute standard tools
2
const result = await context.tools.execute({
3
tool: 'send_email',
4
parameters: { ... }
5
});
6
7
// Execute with specific connected account
8
const result = await context.tools.execute({
9
connected_account_id: 'specific_account',
10
tool: 'send_email',
11
parameters: { ... }
12
});
```
### Connected accounts
[Section titled “Connected accounts”](#connected-accounts)
Access connected account information:
```javascript
1
// Get connected account details
2
const account = await context.accounts.get(accountId);
3
4
// List accounts for a user
5
const accounts = await context.accounts.list({
6
identifier: 'user_123',
7
provider: 'gmail'
8
});
```
### Utilities
[Section titled “Utilities”](#utilities)
Access utility functions:
```javascript
1
// Generate unique IDs
2
const id = context.utils.generateId();
3
4
// Format dates
5
const formatted = context.utils.formatDate(date, 'YYYY-MM-DD');
6
7
// Validate email
8
const isValid = context.utils.isValidEmail(email);
9
10
// HTTP requests
11
const response = await context.utils.httpRequest({
12
url: 'https://api.example.com/data',
13
method: 'GET',
14
headers: { 'Authorization': 'Bearer token' }
15
});
```
### Error handling
[Section titled “Error handling”](#error-handling)
Throw structured errors:
```javascript
1
// Throw validation error
2
throw new context.errors.ValidationError('Invalid email format');
3
4
// Throw business logic error
5
throw new context.errors.BusinessLogicError('User not found');
6
7
// Throw external API error
8
throw new context.errors.ExternalAPIError('GitHub API returned 500');
```
## Testing custom tools
[Section titled “Testing custom tools”](#testing-custom-tools)
### Unit testing
[Section titled “Unit testing”](#unit-testing)
Test custom tools in isolation:
```javascript
1
// Mock context for testing
2
const mockContext = {
3
tools: {
4
execute: jest.fn().mockResolvedValue({
5
message_id: 'test_msg_123',
6
status: 'sent'
7
})
8
},
9
utils: {
10
generateId: () => 'test_id_123',
11
formatDate: (date, format) => '2024-01-15'
12
}
13
};
14
15
// Test custom tool
16
const result = await sendWelcomeEmail.implementation({
17
user_name: 'John Doe',
18
user_email: 'john@example.com',
19
company_name: 'Acme Corp'
20
}, mockContext);
21
22
expect(result.status).toBe('sent');
23
expect(mockContext.tools.execute).toHaveBeenCalledWith({
24
tool: 'send_email',
25
parameters: expect.objectContaining({
26
to: ['john@example.com'],
27
subject: 'Welcome to Acme Corp!'
28
})
29
});
```
### Integration testing
[Section titled “Integration testing”](#integration-testing)
Test with real Agent Auth:
```javascript
1
// Test custom tool with real connections
2
const testResult = await agentConnect.tools.execute({
3
connected_account_id: 'test_gmail_account',
4
tool: 'send_welcome_email',
5
parameters: {
6
user_name: 'Test User',
7
user_email: 'test@example.com',
8
company_name: 'Test Company'
9
}
10
});
11
12
console.log('Test result:', testResult);
```
## Best practices
[Section titled “Best practices”](#best-practices)
### Tool design
[Section titled “Tool design”](#tool-design)
* **Single responsibility**: Each tool should have a clear, single purpose
* **Consistent naming**: Use descriptive, consistent naming conventions
* **Clear documentation**: Provide detailed descriptions and examples
* **Error handling**: Implement comprehensive error handling
* **Input validation**: Validate all input parameters
### Performance optimization
[Section titled “Performance optimization”](#performance-optimization)
* **Parallel execution**: Use Promise.all() for independent operations
* **Caching**: Cache frequently accessed data
* **Batch operations**: Group similar operations together
* **Timeout handling**: Set appropriate timeouts for external calls
### Security considerations
[Section titled “Security considerations”](#security-considerations)
* **Input sanitization**: Sanitize all user inputs
* **Permission checks**: Verify user permissions before execution
* **Sensitive data**: Handle sensitive data securely
* **Rate limiting**: Implement rate limiting for resource-intensive operations
## Custom tool examples
[Section titled “Custom tool examples”](#custom-tool-examples)
### Slack notification tool
[Section titled “Slack notification tool”](#slack-notification-tool)
```javascript
1
const sendSlackNotification = {
2
name: 'send_slack_notification',
3
display_name: 'Send Slack Notification',
4
description: 'Send formatted notifications to Slack with optional mentions',
5
category: 'communication',
6
provider: 'custom',
7
input_schema: {
8
type: 'object',
9
properties: {
10
channel: { type: 'string' },
11
message: { type: 'string' },
12
severity: { type: 'string', enum: ['info', 'warning', 'error'] },
13
mentions: { type: 'array', items: { type: 'string' } }
14
},
15
required: ['channel', 'message']
16
},
17
output_schema: {
18
type: 'object',
19
properties: {
20
message_ts: { type: 'string' },
21
permalink: { type: 'string' }
22
}
23
},
24
implementation: async (parameters, context) => {
25
const { channel, message, severity = 'info', mentions = [] } = parameters;
26
27
const colors = {
28
info: 'good',
29
warning: 'warning',
30
error: 'danger'
31
};
32
33
const mentionText = mentions.length > 0 ?
34
`${mentions.map(m => `<@${m}>`).join(' ')} ` : '';
35
36
return await context.tools.execute({
37
tool: 'send_message',
38
parameters: {
39
channel,
40
text: `${mentionText}${message}`,
41
attachments: [
42
{
43
color: colors[severity],
44
text: message,
45
ts: Math.floor(Date.now() / 1000)
46
}
47
]
48
}
49
});
50
}
51
};
```
### Calendar scheduling tool
[Section titled “Calendar scheduling tool”](#calendar-scheduling-tool)
```javascript
1
const scheduleTeamMeeting = {
2
name: 'schedule_team_meeting',
3
display_name: 'Schedule Team Meeting',
4
description: 'Find available time slots and schedule team meetings',
5
category: 'scheduling',
6
provider: 'custom',
7
input_schema: {
8
type: 'object',
9
properties: {
10
attendees: { type: 'array', items: { type: 'string' } },
11
duration: { type: 'number', minimum: 15 },
12
preferred_times: { type: 'array', items: { type: 'string' } },
13
meeting_title: { type: 'string' },
14
meeting_description: { type: 'string' }
15
},
16
required: ['attendees', 'duration', 'meeting_title']
17
},
18
output_schema: {
19
type: 'object',
20
properties: {
21
event_id: { type: 'string' },
22
scheduled_time: { type: 'string' },
23
attendees_notified: { type: 'number' }
24
}
25
},
26
implementation: async (parameters, context) => {
27
const { attendees, duration, preferred_times, meeting_title, meeting_description } = parameters;
28
29
// Find available time slots
30
const availableSlots = await context.tools.execute({
31
tool: 'find_available_slots',
32
parameters: {
33
attendees,
34
duration,
35
preferred_times: preferred_times || []
36
}
37
});
38
39
if (availableSlots.length === 0) {
40
throw new context.errors.BusinessLogicError('No available time slots found');
41
}
42
43
// Schedule the meeting at the first available slot
44
const selectedSlot = availableSlots[0];
45
const event = await context.tools.execute({
46
tool: 'create_event',
47
parameters: {
48
title: meeting_title,
49
description: meeting_description,
50
start_time: selectedSlot.start_time,
51
end_time: selectedSlot.end_time,
52
attendees
53
}
54
});
55
56
return {
57
event_id: event.event_id,
58
scheduled_time: selectedSlot.start_time,
59
attendees_notified: attendees.length
60
};
61
}
62
};
```
## Versioning and deployment
[Section titled “Versioning and deployment”](#versioning-and-deployment)
### Version management
[Section titled “Version management”](#version-management)
Version your custom tools for backward compatibility:
```javascript
1
const toolV2 = {
2
...originalTool,
3
version: '2.0.0',
4
// Updated implementation
5
};
6
7
// Deploy new version
8
await agentConnect.tools.register(toolV2);
9
10
// Deprecate old version
11
await agentConnect.tools.deprecate(originalTool.name, '1.0.0');
```
### Deployment strategies
[Section titled “Deployment strategies”](#deployment-strategies)
* **Blue-green deployment**: Deploy new version alongside old version
* **Canary deployment**: Gradually roll out to subset of users
* **Feature flags**: Use feature flags to control tool availability
* **Rollback strategy**: Plan for quick rollback if issues arise
Note
**Ready to build?** Start with simple custom tools and gradually add complexity. Test thoroughly before deploying to production, and consider the impact on your users when making changes.
Custom tools unlock the full potential of Agent Auth by allowing you to create specialized workflows that perfectly match your business needs. With proper design, testing, and deployment practices, you can build powerful tools that enhance your team’s productivity and streamline complex operations.
---
# DOCUMENT BOUNDARY
---
# Scalekit optimized built-in tools
> Call Scalekit's pre-built tools across 200+ connectors. Each tool returns structured, LLM-ready output with no endpoint URLs, auth headers, or parsing needed.
Scalekit ships pre-built tools for every connector in the catalog: GitHub, Gmail, Slack, Salesforce, Notion, Linear, HubSpot, and more. Each tool has an LLM-ready schema and returns structured output. Your agent passes inputs; Scalekit injects the user’s credentials and handles the API call.
This page assumes you have an `ACTIVE` connected account for the user. If not, see [Authorize a user](/agentkit/tools/authorize/).
## Get available tools for a user
[Section titled “Get available tools for a user”](#get-available-tools-for-a-user)
Use `list_scoped_tools` / `listScopedTools` to get the tools this specific user is authorized to call. **This is the list you pass to your LLM.**
* Python
```python
1
from google.protobuf.json_format import MessageToDict
2
3
scoped_response, _ = actions.tools.list_scoped_tools(
4
identifier="user_123",
5
filter={"connection_names": ["github-connect"]}, # optional; omit for all connectors
6
page_size=100, # fetch beyond the default page
7
)
8
for scoped_tool in scoped_response.tools:
9
definition = MessageToDict(scoped_tool.tool).get("definition", {})
10
print(definition.get("name"))
11
print(definition.get("input_schema")) # JSON Schema; pass directly to your LLM
```
* Node.js
```typescript
1
const { tools } = await scalekit.tools.listScopedTools('user_123', {
2
filter: { connectionNames: ['github-connect'] }, // use filter: {} to list every connector
3
pageSize: 100, // fetch beyond the default page
4
});
5
for (const tool of tools) {
6
const { name, input_schema } = tool.tool.definition;
7
console.log(name, input_schema); // JSON Schema; pass directly to your LLM
8
}
```
To explore tools interactively, use the playground at [**Scalekit Dashboard**](https://app.scalekit.com) **> AgentKit > Playground**.
## Execute a tool
[Section titled “Execute a tool”](#execute-a-tool)
Use `execute_tool` / `executeTool` to run a named tool for a specific user. Scalekit identifies the connected account with:
* User identifier (`identifier`) + Connection name as shown in the Scalekit Dashboard (`connection_name`), or
* Connected Account ID (`connected_account_id`) — autogenerated by Scalekit and visible in the Scalekit Dashboard
- Python
```python
1
# connected account is selected using the user identifier and the connection name
2
result = actions.execute_tool(
3
tool_name="github_user_repos_list",
4
identifier="user_123",
5
connection_name="github-connect",
6
tool_input={"per_page": 5, "sort": "updated"},
7
)
8
print(result.data)
9
10
# alternatively, use the connected account ID
11
# result = actions.execute_tool(
12
# tool_name="github_user_repos_list",
13
# connected_account_id="ca_xxxxxx",
14
# tool_input={"per_page": 5, "sort": "updated"},
15
# )
```
- Node.js
```typescript
1
// connected account is selected using the user identifier and the connector
2
const result = await scalekit.actions.executeTool({
3
toolName: 'github_user_repos_list',
4
identifier: 'user_123',
5
connector: 'github-connect',
6
toolInput: { per_page: 5, sort: 'updated' },
7
});
8
console.log(result.data);
9
10
// alternatively, use the connected account ID
11
// const result = await scalekit.actions.executeTool({
12
// toolName: 'github_user_repos_list',
13
// connectedAccountId: 'ca_xxxxxx',
14
// toolInput: { per_page: 5, sort: 'updated' },
15
// });
```
## Understand tool response shape
[Section titled “Understand tool response shape”](#understand-tool-response-shape)
`execute_tool` / `executeTool` returns a **wrapper object**, not the provider payload directly. Tool output lives under `response.data` (Python) or `result.data` (Node.js). Keys inside `data` depend on the tool you called.
When you integrate a new tool, log the full wrapper once, then read fields from `data`:
* Python
List Google Calendar events (Python)
```python
1
response = actions.execute_tool(
2
tool_name="googlecalendar_list_events",
3
identifier="user_123",
4
connection_name="googlecalendar",
5
tool_input={"max_results": 10},
6
)
7
8
# Security: Log only in development; production logs may expose user data.
9
print(response.data)
10
11
events = response.data.get("events", [])
12
next_page_token = response.data.get("next_page_token")
13
print(f"Found {len(events)} events")
```
* Node.js
List Google Calendar events (Node.js)
```typescript
1
const result = await scalekit.actions.executeTool({
2
toolName: 'googlecalendar_list_events',
3
identifier: 'user_123',
4
connector: 'googlecalendar',
5
toolInput: { max_results: 10 },
6
});
7
8
// Security: Log only in development; production logs may expose user data.
9
console.log(result.data);
10
11
const events = (result.data as { events?: unknown[] }).events ?? [];
12
const nextPageToken = (result.data as { next_page_token?: string }).next_page_token;
13
console.log(`Found ${events.length} events`);
```
Do not treat the wrapper as the tool payload
A common integration mistake is parsing `response` as if it were a flat list of events. Always read `response.data` first, then extract tool-specific keys such as `events` and `next_page_token`.
## Wire into your LLM
[Section titled “Wire into your LLM”](#wire-into-your-llm)
The full agent loop: fetch scoped tools → pass to LLM → execute tool calls → feed results back.
* Python
```python
1
import anthropic
2
from google.protobuf.json_format import MessageToDict
3
4
client = anthropic.Anthropic()
5
6
# 1. Fetch tools scoped to this user
7
scoped_response, _ = actions.tools.list_scoped_tools(
8
identifier="user_123",
9
filter={"connection_names": ["github-connect"]},
10
page_size=100, # fetch beyond the default page so no connector tools are missed
11
)
12
llm_tools = [
13
{
14
"name": MessageToDict(t.tool).get("definition", {}).get("name"),
15
"description": MessageToDict(t.tool).get("definition", {}).get("description"),
16
"input_schema": MessageToDict(t.tool).get("definition", {}).get("input_schema", {}),
17
}
18
for t in scoped_response.tools
19
]
20
21
# 2. Send to LLM
22
messages = [{"role": "user", "content": "Summarize my 5 most recently updated repositories"}]
23
response = client.messages.create(
24
model="claude-sonnet-4-6",
25
max_tokens=1024,
26
tools=llm_tools,
27
messages=messages,
28
)
29
30
# 3. Execute tool calls and feed results back
31
for block in response.content:
32
if block.type == "tool_use":
33
tool_result = actions.execute_tool(
34
tool_name=block.name,
35
identifier="user_123",
36
tool_input=block.input,
37
)
38
messages.append({"role": "assistant", "content": response.content})
39
messages.append({
40
"role": "user",
41
"content": [{"type": "tool_result", "tool_use_id": block.id, "content": str(tool_result.data)}],
42
})
```
* Node.js
```typescript
1
import Anthropic from '@anthropic-ai/sdk';
2
3
const anthropic = new Anthropic();
4
5
// 1. Fetch tools scoped to this user
6
const { tools } = await scalekit.tools.listScopedTools('user_123', {
7
filter: { connectionNames: ['github-connect'] },
8
pageSize: 100, // fetch beyond the default page so no connector tools are missed
9
});
10
const llmTools = tools.map((t) => ({
11
name: t.tool.definition.name,
12
description: t.tool.definition.description,
13
input_schema: t.tool.definition.input_schema,
14
}));
15
16
// 2. Send to LLM
17
const messages: Anthropic.MessageParam[] = [
18
{ role: 'user', content: 'Summarize my 5 most recently updated repositories' },
19
];
20
const response = await anthropic.messages.create({
21
model: 'claude-sonnet-4-6',
22
max_tokens: 1024,
23
tools: llmTools,
24
messages,
25
});
26
27
// 3. Execute tool calls and feed results back
28
for (const block of response.content) {
29
if (block.type === 'tool_use') {
30
const toolResult = await scalekit.actions.executeTool({
31
toolName: block.name,
32
identifier: 'user_123',
33
toolInput: block.input as Record,
34
});
35
messages.push({ role: 'assistant', content: response.content });
36
messages.push({
37
role: 'user',
38
content: [{ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(toolResult.data) }],
39
});
40
}
41
}
```
## Use a framework adapter
[Section titled “Use a framework adapter”](#use-a-framework-adapter)
For LangChain and Google ADK, Scalekit returns native tool objects in Python with no schema reshaping needed.
* LangChain
```python
1
from langchain_openai import ChatOpenAI
2
from langchain.agents import create_agent
3
4
tools = actions.langchain.get_tools(
5
identifier="user_123",
6
connection_names=["github-connect"],
7
page_size=100, # avoid missing tools when a connector has more than the default page
8
)
9
llm = ChatOpenAI(model="claude-sonnet-4-6")
10
agent = create_agent(model=llm, tools=tools, system_prompt="You are a helpful assistant.")
11
result = agent.invoke({"messages": [{"role": "user", "content": "List my 5 most recently updated repositories"}]})
```
* Google ADK
```python
1
from google.adk.agents import Agent
2
from google.adk.models.lite_llm import LiteLlm
3
4
github_tools = actions.google.get_tools(
5
identifier="user_123",
6
connection_names=["github-connect"],
7
page_size=100, # avoid missing tools when a connector has more than the default page
8
)
9
agent = Agent(
10
name="github_assistant",
11
model=LiteLlm(model="claude-sonnet-4-6"),
12
tools=github_tools,
13
)
```
* Node.js (Vercel AI SDK)
```typescript
1
import { generateText, jsonSchema, tool } from 'ai';
2
3
const { tools: scopedTools } = await scalekit.tools.listScopedTools('user_123', {
4
filter: { connectionNames: ['github-connect'] },
5
pageSize: 100, // fetch beyond the default page so no connector tools are missed
6
});
7
const tools = Object.fromEntries(
8
scopedTools.map((t) => [
9
t.tool.definition.name,
10
tool({
11
description: t.tool.definition.description,
12
parameters: jsonSchema(t.tool.definition.input_schema ?? { type: 'object', properties: {} }),
13
execute: async (args) => {
14
const result = await scalekit.actions.executeTool({
15
toolName: t.tool.definition.name,
16
toolInput: args,
17
identifier: 'user_123',
18
});
19
return result.data;
20
},
21
}),
22
]),
23
);
```
MCP-compatible frameworks
Prefer a single interface any MCP client can consume? See [Virtual MCP Servers](/agentkit/mcp/overview/).
## Troubleshooting
[Section titled “Troubleshooting”](#troubleshooting)
Connected account stays in `PENDING`
The user hasn’t completed the OAuth flow yet. Call `get_authorization_link` and redirect the user to the link. Retry after consent completes.
Tool call fails with resource not found
Check three things:
* The connector name exists in **AgentKit** > **Connections**
* The `identifier` matches the one used when creating the connected account
* Call `list_scoped_tools` and only execute tool names it returns
Connection names differ across environments
Connection names are workspace-specific. Don’t hard-code them. Use environment variables (`GITHUB_CONNECTION_NAME`, `GMAIL_CONNECTION_NAME`) and reference those in API calls.
If you need an endpoint not covered by optimized tools, see [Custom tools](/agentkit/tools/custom-tools/).
---
# DOCUMENT BOUNDARY
---
# Verify user identity
> Confirm that the user who completed the OAuth consent is the same user your app intended to connect.
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, before activating a connected account, Scalekit confirms that the user who completed the OAuth consent is the same user your app intended to connect. This **user verification** step runs every time a connected account is authorized and prevents OAuth consent from activating on the wrong account.
Choose a mode in **AgentKit** > **User Verification**:
* **Custom user verification**: Your server confirms the authorizing user matches the user your app intended to connect. Use in production. Without this, any user who receives an authorization link can activate a connected account (including the wrong one).
* **Scalekit users only**: Scalekit checks that the authorizing user is signed in to your Scalekit dashboard. No code required. Use during development and internal testing when all users are already on your team.
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 verification** before onboarding real users.
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
[Section titled “Implement verification in your app”](#implement-verification-in-your-app)
If you haven’t installed the SDK yet, see the [quickstart](/agentkit/quickstart/).
### Generate the authorization link
[Section titled “Generate the authorization link”](#generate-the-authorization-link)
Pass these fields when creating the authorization link:
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| `identifier` | **Required.** Your user’s ID or email. Scalekit stores this and checks it matches at verify time. |
| `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
```python
1
import secrets
2
3
# Generate a state value to prevent CSRF
4
state = secrets.token_urlsafe(32)
5
# Store state in a secure, HTTP-only cookie to validate on callback
6
7
response = scalekit_client.actions.get_authorization_link(
8
connection_name=connector,
9
identifier=user_id,
10
user_verify_url="https://app.yourapp.com/user/verify",
11
state=state,
12
)
```
* Node.js
```typescript
1
import crypto from 'node:crypto';
2
3
// Generate a state value to prevent CSRF
4
const state = crypto.randomUUID();
5
// Store state in a secure, HTTP-only cookie to validate on callback
6
7
const { link } = await scalekit.actions.getAuthorizationLink({
8
identifier: userId,
9
connectionName: connector,
10
userVerifyUrl: 'https://app.yourapp.com/user/verify',
11
state,
12
});
```
### Handle the verification callback
[Section titled “Handle the verification callback”](#handle-the-verification-callback)
After OAuth completes, Scalekit redirects to your `user_verify_url`:
```http
1
GET https://app.yourapp.com/user/verify?auth_request_id=req_xyz&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
```python
1
# 1. Validate state from query param matches state in cookie
2
# 2. Read user identity from your session, not from the URL
3
4
response = scalekit_client.actions.verify_connected_account_user(
5
auth_request_id=auth_request_id,
6
identifier=user_id, # must match what was stored at link creation
7
)
8
# On success: redirect to response.post_user_verify_redirect_url
```
* Node.js
```typescript
1
// 1. Validate state from query param matches state in cookie
2
// 2. Read user identity from your session, not from the URL
3
4
const { postUserVerifyRedirectUrl } =
5
await scalekit.actions.verifyConnectedAccountUser({
6
authRequestId: auth_request_id,
7
identifier: userId, // must match what was stored at link creation
8
});
9
// On success: redirect to postUserVerifyRedirectUrl
```
On success, the connected account is activated. Redirect the user using `post_user_verify_redirect_url`.
## Common scenarios
[Section titled “Common scenarios”](#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 connection is set to **Custom user verification**, 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](#handle-the-verification-callback) at that URL.
* **In development or internal testing**, set the mode to **Scalekit users only** in **AgentKit** > **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.
---
# DOCUMENT BOUNDARY
---
# User authentication flow
> Learn how Scalekit routes users through authentication based on login method and organization SSO policies.
The user’s authentication journey on the hosted login page can differ based on the **login method** they choose and the **organization policies** configured in Scalekit.
## Organization policies
[Section titled “Organization policies”](#organization-policies)
Organizations can enforce Enterprise SSO for their users. An organization must create an enabled [SSO connection](/authenticate/auth-methods/enterprise-sso/) and add [organization domains](/authenticate/manage-users-orgs/organization-domains/).
Scalekit uses **Home Realm Discovery (HRD)** to determine whether a user’s email domain matches a configured organization domain. When a match is found, the user is routed to that organization’s SSO identity provider.
**Examples**
* A user tries to log in as `user@samecorp.com` on the hosted login page. If `samecorp.com` is registered as an organization domain with SSO enabled, the user is redirected to that organization’s IdP to complete authentication.
* A user tries to log in with Google as `user@samecorp.com` on the hosted login page. If `samecorp.com` is registered as an organization domain with SSO enabled, the user is redirected to that organization’s IdP after returning from Google.
## Login method–specific behavior
[Section titled “Login method–specific behavior”](#login-methodspecific-behavior)
Scalekit allows users to choose different login methods on the hosted login page. The timing of organization domain checks differs slightly by method, but the rules remain consistent.
### Social login
[Section titled “Social login”](#social-login)
* User authenticates with a social IdP (e.g., Google, GitHub).
* Scalekit evaluates the user’s email after social auth completes.
* Home Realm Discovery (HRD) checks whether the email domain matches an organization domain.
* **Domain match:** User is redirected to the organization’s SSO IdP.
* **No match:** Authentication completes.
This ensures that enterprise users must complete SSO authentication even if they initially choose social login.
### Passkey login
[Section titled “Passkey login”](#passkey-login)
* User authenticates using a passkey.
* Authentication succeeds immediately.
* Scalekit performs Home Realm Discovery (HRD) to check the email domain.
* **Domain match:** User is redirected to SSO.
* **No match:** Authentication completes.
Passkeys authenticate the user, but do not override organization SSO policy.
### Email-based login
[Section titled “Email-based login”](#email-based-login)
* User enters their email address.
* Home Realm Discovery (HRD) runs **before authentication** to check the email domain.
* **Domain match:** User is redirected to SSO.
* **No match:** Scalekit performs OTP or magic link verification, then authentication completes.
### Authentication flow
[Section titled “Authentication flow”](#authentication-flow)
This diagram shows the different variations of user’s authentication journey on the hosted login page.
***
## Enterprise SSO Trust model
[Section titled “Enterprise SSO Trust model”](#enterprise-sso-trust-model)
Most enterprise identity providers (IdPs) like Okta or Microsoft Entra do not prove that a user actually controls the email inbox they sign in with. They only assert an email address in the SAML/OIDC token. Because of this, when a user logs in via Enterprise SSO, Scalekit does not automatically treat that SSO connection as a trusted source of email ownership.
Since Scalekit cannot be sure that the SSO user truly owns the email address, the user is taken through an email ownership check (magic link or OTP) to prove control of that inbox. After the user successfully verifies their email, that SSO connection is marked as a verified channel for that specific user, and they do not need to verify email ownership again on subsequent logins via the same connection.
If you want an Enterprise SSO connection to be treated as a trusted provider for a specific domain, you can assign one or more domains to the organization. Then, for users logging in via that Enterprise SSO connection whose email address matches one of the configured domains, Scalekit skips additional email ownership verification.
| SSO trust case | Example | Result |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Trusted SSO | Org has added `acmecorp.com` in organization domain. User authenticates as `user@acmecorp.com` with organization SSO. | Email ownership trusted |
| Untrusted SSO | Org has added `acmecorp.com` in organization domain and user authenticates as `user@foocorp.com` with organization SSO. | Email ownership not trusted → Additional verification required |
***
## Forcing SSO from your application
[Section titled “Forcing SSO from your application”](#forcing-sso-from-your-application)
Your app can override Home Realm Discovery (HRD) by passing `organization_id` or `connection_id` in the authentication request ↗ to Scalekit. When you do this:
* Scalekit skips HRD and redirects the user directly to the specified SSO IdP.
* After SSO authentication completes, Scalekit checks whether the user’s email domain matches one of the organization domains configured on that SSO connection.
* **Domain match**: authentication completes.
* **No match**: Scalekit requires additional verification (OTP or magic link) before completing authentication.
## IdP‑initiated SSO
[Section titled “IdP‑initiated SSO”](#idpinitiated-sso)
In IdP‑initiated SSO, authentication starts at the identity provider instead of your application or the hosted login page. After the IdP authenticates the user and redirects to Scalekit, Scalekit evaluates email ownership trust:
* If the user’s email domain matches one of the organization domains configured on the SSO connection, authentication completes.
* If the email domain does not match, Scalekit requires additional verification (OTP or magic link) before completing authentication.
This workflow ensures IdP‑initiated flows follow the same email ownership and trust guarantees as app‑initiated SSO
***
## Account linking
[Section titled “Account linking”](#account-linking)
### What happens
[Section titled “What happens”](#what-happens)
Scalekit maintains a single user record per email address. For example, if a user first authenticates with passwordless login (magic link/OTP) and later uses Google or Enterprise SSO, Scalekit links both identities to the same user record. These identities are stored on the user object for your app to read if needed. This avoids duplicate users when people switch authentication methods.
### Why it is safe
[Section titled “Why it is safe”](#why-it-is-safe)
Scalekit only treats an SSO IdP as a trusted source of email ownership when:
* the authenticated email domain matches one of the organization domains configured on the SSO connection, or
* the user has previously proven email ownership via magic link or OTP.
Because the organization has proven domain ownership, and/or the user has proven inbox control, emails from that SSO connection are treated as valid. This prevents attackers from linking identities unless email ownership has been verified through trusted mechanisms.
---
# DOCUMENT BOUNDARY
---
# Implement enterprise SSO
> How to implement enterprise SSO for your application
Enterprise single sign-on (SSO) enables users to authenticate using their organization’s identity provider (IdP), such as Okta, Azure AD, or Google Workspace. [After completing the quickstart](/authenticate/fsa/quickstart/), follow this guide to implement SSO for an organization, streamline admin onboarding, enforce login requirements, and validate your configuration.
1. ## Enable SSO for the organization
[Section titled “Enable SSO for the organization”](#enable-sso-for-the-organization)
When a user signs up for your application, Scalekit automatically creates an organization and assigns an admin role to the user. Provide an option in your user interface to enable SSO for the organization or workspace.
Here’s how you can do that with Scalekit. Use the following SDK method to activate SSO for the organization:
* Node.js
Enable SSO
```javascript
const settings = {
features: [
{
name: 'sso',
enabled: true,
}
],
};
await scalekit.organization.updateOrganizationSettings(
'', // Get this from the idToken or accessToken
settings
);
```
* Python
Enable SSO
```python
settings = [
{
"name": "sso",
"enabled": True
}
]
scalekit.organization.update_organization_settings(
organization_id='', # Get this from the idToken or accessToken
settings=settings
)
```
* Java
Enable SSO
```java
OrganizationSettingsFeature featureSSO = OrganizationSettingsFeature.newBuilder()
.setName("sso")
.setEnabled(true)
.build();
updatedOrganization = scalekitClient.organizations()
.updateOrganizationSettings(organizationId, List.of(featureSSO));
```
* Go
Enable SSO
```go
settings := OrganizationSettings{
Features: []Feature{
{
Name: "sso",
Enabled: true,
},
},
}
organization, err := sc.Organization().UpdateOrganizationSettings(ctx, organizationId, settings)
if err != nil {
// Handle error
}
```
You can also enable this from the [organization settings](/authenticate/fsa/user-management-settings/) in the Scalekit dashboard.
2. ## Enable admin portal for enterprise customer onboarding
[Section titled “Enable admin portal for enterprise customer onboarding”](#enable-admin-portal-for-enterprise-customer-onboarding)
After SSO is enabled for that organization, provide a method for configuring a SSO connection with the organization’s identity provider.
Scalekit offers two primary approaches:
* Generate a link to the admin portal from the Scalekit dashboard and share it with organization admins via your usual channels.
* Or embed the admin portal in your application in an inline frame so administrators can configure their IdP without leaving your app.
[See how to onboard enterprise customers](/sso/guides/onboard-enterprise-customers/)
3. ## Identify and enforce SSO for organization users
[Section titled “Identify and enforce SSO for organization users”](#identify-and-enforce-sso-for-organization-users)
Administrators typically register [organization-owned domains](/authenticate/manage-users-orgs/organization-domains/) through the admin portal. When a user attempts to sign in with an email address matching a registered domain, they are automatically redirected to their organization’s designated identity provider for authentication. This is also known as **Home Realm Discovery**.
**Organization domains** automatically route users to the correct SSO connection based on their email address. When a user signs in with an email domain that matches a registered organization domain, Scalekit redirects them to that organization’s SSO provider and enforces SSO login.
For example, if an organization registers `megacorp.org`, any user signing in with an `joe@megacorp.org` email address is redirected to Megacorp’s SSO provider.
Navigate to **Dashboard > Organizations** and select the target organization > **Overview** > **Organization Domains** section to register organization domains.
4. ## Test your SSO integration
[Section titled “Test your SSO integration”](#test-your-sso-integration)
Scalekit offers a “Test Organization” feature that enables SSO flow validation without requiring test accounts from your customers’ identity providers.
To quickly test the integration, enter an email address using the domains `joe@example.com` or `jane@example.org`. This will trigger a redirect to the IdP simulator, which serves as the test organization’s identity provider for authentication.
For a comprehensive step-by-step walkthrough, refer to the [Test SSO integration guide](/sso/guides/test-sso/).
---
# DOCUMENT BOUNDARY
---
# Add passkeys login method
> Enable passkey authentication for your users
Passkeys replace passwords with biometric authentication (fingerprint, face recognition) or device PINs. Built on FIDO® standards (WebAuthn and CTAP), passkeys offer superior security by eliminating phishing and credential stuffing vulnerabilities, while also providing a seamless one-tap login experience. Unlike traditional authentication methods, passkeys sync across devices, removing the need for multiple enrollments and providing better recovery options when devices are lost.
Your [existing Scalekit integration](/authenticate/fsa/quickstart) already supports passkeys. To implement, enable passkeys in the Scalekit dashboard and leverage Scalekit’s built-in user passkey registration functionality.
1. ## Enable passkeys in the Scalekit dashboard
[Section titled “Enable passkeys in the Scalekit dashboard”](#enable-passkeys-in-the-scalekit-dashboard)
Go to Scalekit Dashboard > Authentication > Auth methods > Passkeys and click “Enable”
2. ## Manage passkey registration
[Section titled “Manage passkey registration”](#manage-passkey-registration)
Let users manage passkeys just by redirecting them to Scalekit from your app (usually through a button in your app that says “Manage passkeys”), or building your own UI.
#### Using Scalekit UI
[Section titled “Using Scalekit UI”](#using-scalekit-ui)
To enable users to register and manage their passkeys, redirect them to the Scalekit passkey registration page.
Construct the URL by appending `/ui/profile/passkeys` to your Scalekit environment URL
Passkey Registration URL
```js
/ui/profile/passkeys
```
This opens a page where users can:
* Register new passkeys
* Remove existing passkeys
* View their registered passkeys
Note
Scalekit registers & authenticates user’s passkeys through the browser’s native passkey API. This API prompts users to authenticate with device-supported passkeys — such as fingerprint, PIN, or password managers.
To show the page on your own domain instead of the default Scalekit domain, configure a [branded custom domain](/guides/custom-domain). Users then see a URL such as `https://auth.yourapp.com/ui/profile/passkeys`.
#### In your own UI
[Section titled “In your own UI”](#in-your-own-ui)
If you prefer to create a custom user interface for passkey management, Scalekit offers comprehensive APIs that enable you to build a personalized experience. These APIs allow you to list registered passkeys, rename them, and remove them entirely. However registration of passkeys is only supported through the Scalekit UI.
* Node.js
List user's passkeys
```js
// : fetch from Access Token or ID Token after identity verification
const res = await fetch(
'/api/v1/webauthn/credentials?user_id=',
{ headers: { Authorization: 'Bearer ' } }
);
const data = await res.json();
console.log(data);
```
Rename a passkey
```js
// : obtained from list response (id of each passkey)
await fetch('/api/v1/webauthn/credentials/', {
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer '
},
body: JSON.stringify({ display_name: '' })
});
```
Remove a passkey
```js
// : obtained from list response (id of each passkey)
await fetch('/api/v1/webauthn/credentials/', {
method: 'DELETE',
headers: { Authorization: 'Bearer ' }
});
```
* Python
List user's passkeys
```python
import requests
# : fetch from access token or ID token after identity verification
r = requests.get(
'/api/v1/webauthn/credentials',
params={'user_id': ''},
headers={'Authorization': 'Bearer '}
)
print(r.json())
```
Rename a passkey
```python
import requests
# : obtained from list response (id of each passkey)
requests.patch(
'/api/v1/webauthn/credentials/',
json={'display_name': ''},
headers={'Authorization': 'Bearer '}
)
```
Remove a passkey
```python
import requests
# : obtained from list response (id of each passkey)
requests.delete(
'/api/v1/webauthn/credentials/',
headers={'Authorization': 'Bearer '}
)
```
* Java
List user's passkeys
```java
var client = java.net.http.HttpClient.newHttpClient();
// : fetch from Access Token or ID Token after identity verification
var req = java.net.http.HttpRequest.newBuilder(
java.net.URI.create("/api/v1/webauthn/credentials?user_id=")
)
.header("Authorization", "Bearer ")
.GET().build();
var res = client.send(req, java.net.http.HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
```
Rename a passkey
```java
var client = java.net.http.HttpClient.newHttpClient();
var body = "{\"display_name\":\"\"}";
// : obtained from list response (id of each passkey)
var req = java.net.http.HttpRequest.newBuilder(
java.net.URI.create("/api/v1/webauthn/credentials/")
)
.header("Authorization", "Bearer ")
.header("Content-Type","application/json")
.method("PATCH", java.net.http.HttpRequest.BodyPublishers.ofString(body))
.build();
client.send(req, java.net.http.HttpResponse.BodyHandlers.discarding());
```
Remove a passkey
```java
var client = java.net.http.HttpClient.newHttpClient();
// : obtained from list response (id of each passkey)
var req = java.net.http.HttpRequest.newBuilder(
java.net.URI.create("/api/v1/webauthn/credentials/")
)
.header("Authorization", "Bearer ")
.DELETE().build();
client.send(req, java.net.http.HttpResponse.BodyHandlers.discarding());
```
* Go
List user's passkeys
```go
// imports: net/http, io, fmt
// : fetch from access token or ID token after identity verification
req, _ := http.NewRequest("GET", "/api/v1/webauthn/credentials?user_id=", nil)
req.Header.Set("Authorization", "Bearer ")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))
```
Rename a passkey
```go
// imports: net/http, bytes
payload := bytes.NewBufferString(`{"display_name":""}`)
// : obtained from list response (id of each passkey)
req, _ := http.NewRequest("PATCH", "/api/v1/webauthn/credentials/", payload)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer ")
http.DefaultClient.Do(req)
```
Remove a passkey
```go
// imports: net/http
// : obtained from list response (id of each passkey)
req, _ := http.NewRequest("DELETE", "/api/v1/webauthn/credentials/", nil)
req.Header.Set("Authorization", "Bearer ")
http.DefaultClient.Do(req)
```
Note
All API requests require an access token obtained via the OAuth 2.0 client credentials flow. Follow [Authenticate with the Scalekit API](/guides/authenticate-scalekit-api), then replace `` in the examples below.
3. ## Users can log in with passkeys
[Section titled “Users can log in with passkeys”](#users-can-log-in-with-passkeys)
Users who have registered passkeys can log in with them.
This time when login page shows, users can select “Passkey” as the authentication method.
During sign-up, you’ll continue to use established authentication methods like [verification codes, magic links](/authenticate/auth-methods/passwordless/) or [social logins](/authenticate/auth-methods/social-logins/). Once a user is registered, they can then add passkeys as an additional, convenient login option.
---
# DOCUMENT BOUNDARY
---
# Sign in with magic link or Email OTP
> Enable passwordless sign-in with email verification codes or magic links
Configure Magic Link & OTP to enable passwordless authentication for your application. After completing the [quickstart guide](/authenticate/fsa/quickstart/), set up email verification codes or magic links so users can sign in without passwords.
Switch between those passwordless methods without modifying any code:
| Method | How it works | Best for |
| ------------------------------ | ---------------------------------------------------------------- | -------------------------------------------- |
| Verification code | Users receive a one-time code via email and enter it in your app | Applications requiring explicit verification |
| Magic link | Users click a link in their email to authenticate | Quick, frictionless sign-in |
| Magic link + Verification code | Users choose either method | Maximum flexibility and user choice |
## Configure magic link or OTP
[Section titled “Configure magic link or OTP”](#configure-magic-link-or-otp)
In the Scalekit dashboard, go to **Authentication > Auth methods > Magic Link & OTP**
1. ### Select authentication method
[Section titled “Select authentication method”](#select-authentication-method)
Choose one of three methods:
* **Verification code** - Users enter a 6-digit code sent to their email
* **Magic link** - Users click a link in their email to authenticate
* **Magic link + Verification code** - Users can choose either method
2. ### Set expiry period
[Section titled “Set expiry period”](#set-expiry-period)
Configure how long verification codes and magic links remain valid:
* **Default**: 300 seconds (5 minutes)
* **Range**: 60 to 3600 seconds
* **Recommendation**: 300 seconds balances security and usability
Note
While shorter expiry periods enhance security by reducing the window for potential unauthorized access, they can negatively impact user experience, especially with shorter email-to-input times. Conversely, longer periods provide more convenience but increase the risk of credential misuse if intercepted.
## Enforce same browser origin
[Section titled “Enforce same browser origin”](#enforce-same-browser-origin)
When enforcing same browser origin, users are required to complete magic link authentication within the same browser where they initiated the login process. This security feature is particularly recommended for applications dealing with sensitive data or financial transactions, as it adds an extra layer of protection against potential unauthorized access attempts.
**Example scenario**: A healthcare app where a user requests a magic link on their laptop. If someone intercepts the email and tries to open it on a different device, the authentication fails.
## Regenerate credentials on resend
[Section titled “Regenerate credentials on resend”](#regenerate-credentials-on-resend)
When a user requests a new Magic Link or Email OTP, the system generates a fresh code or link while automatically invalidating the previous one. This approach is recommended for all applications as a critical security measure to prevent potential misuse of compromised credentials.
**Example scenario**: A user requests a verification code but doesn’t receive it. They request a new code. With this setting enabled, the first code becomes invalid, preventing unauthorized access if the original email was intercepted.
---
# DOCUMENT BOUNDARY
---
# Add social login to your app
> Implement authentication with Google, Microsoft, GitHub, and other social providers
First, complete the [quickstart guide](/authenticate/fsa/quickstart/) to integrate Scalekit auth into your application. Scalekit natively supports OAuth 2.0, enabling you to easily configure social login providers that will automatically appear as authentication options on your login page.
1. ## Configure social login providers
[Section titled “Configure social login providers”](#configure-social-login-providers)
Google login is pre-configured in all development environments for simplified testing. You can integrate additional social login providers by setting up your own connection credentials with each provider.
Navigate to **Authentication** > **Auth Methods** > **Social logins** in your dashboard to configure these settings
### Google
Enable users to sign in with their Google accounts using OAuth 2.0
[Setup →](/guides/integrations/social-connections/google)
### GitHub
Allow users to authenticate using their GitHub credentials
[Setup →](/guides/integrations/social-connections/github)
### Microsoft
Integrate Microsoft accounts for seamless user authentication
[Setup →](/guides/integrations/social-connections/microsoft)
### GitLab
Enable GitLab-based authentication for your application
[Setup →](/guides/integrations/social-connections/gitlab)
### LinkedIn
Let users sign in with their LinkedIn accounts using OAuth 2.0
[Setup →](/guides/integrations/social-connections/linkedin)
### Salesforce
Enable Salesforce-based authentication for your application
[Setup →](/guides/integrations/social-connections/salesforce)
2. ## Test the social connection
[Section titled “Test the social connection”](#test-the-social-connection)
After configuration, test the social connection by clicking on “Test Connection” in the dashboard. You will be redirected to the provider’s consent screen to authorize access. A summary table will show the information that will be sent to your app.
## Access social login options on your login page
[Section titled “Access social login options on your login page”](#access-social-login-options-on-your-login-page)
Your application now supports social logins.
Begin the [login process](/authenticate/fsa/implement-login/) to experience the available social login options. Users can authenticate using providers like Google, GitHub, Microsoft, and any others you have set up.
---
# DOCUMENT BOUNDARY
---
# Assign roles to users
> Learn how to assign roles to users in your application using to dashboard, SDK, or automated provisioning
After registering roles and permissions for your application, Scalekit provides multiple ways to assign roles to users. These roles allow your app to make the access control decisions as scalekit sends them to your app in the access token.
## Auto assign roles as users join organizations
[Section titled “Auto assign roles as users join organizations”](#auto-assign-roles-as-users-join-organizations)
By default, the organization creator automatically receives the `admin` role, while users who join later receive the `member` role. You can customize these defaults to match your application’s security requirements. For instance, in a CRM system, you may want to set the default role for new members to a read-only role like `viewer` to prevent accidental data modifications.
1. Go to **Dashboard** > **Roles & Permissions** > **Roles** tab
2. Select the roles available and choose defaults for organization creator and member
This automatically assigns these roles to every users who joins any organization in your Scalekit environment.
## Set a default role for new organization members
[Section titled “Set a default role for new organization members”](#set-a-default-role-for-new-organization-members)
You can also configure a default role that is automatically assigned to users who join a specific organization. This organization-level setting **overrides** the application-level default role described above, allowing finer-grained control per organization. 
## Let users assign roles to others API
[Section titled “Let users assign roles to others ”](#let-users-assign-roles-to-others-)
Enable organization administrators to manage user roles directly within your application. By building features like “Change role” or “Assign permissions” into your app, you can provide a management experience without requiring administrators to leave your app.
To implement role assignment functionality, follow these essential prerequisites:
1. **Verify administrator permissions**: Ensure the user performing the role assignment has the `admin` role or an equivalent role with the necessary permissions. Check the `permissions` property in their access token to confirm they have role management capabilities.
* Node.js
Verify permissions
```javascript
1
// Decode JWT and check admin permissions
2
const decodedToken = decodeJWT(adminAccessToken);
3
4
// Check if user has admin role or required permissions
5
const isAdmin = decodedToken.roles.includes('admin');
6
const hasPermission = decodedToken.permissions?.includes('users.write') ||
7
decodedToken.permissions?.includes('roles.assign');
8
9
if (!isAdmin && !hasPermission) {
10
throw new Error('Insufficient permissions to assign roles');
11
}
```
* Python
Verify permissions
```python
1
# Decode JWT and check admin permissions
2
decoded_token = decode_jwt(access_token)
3
4
# Check if user has admin role or required permissions
5
is_admin = 'admin' in decoded_token.get('roles', [])
6
has_permission = any(perm in decoded_token.get('permissions', [])
7
for perm in ['users.write', 'roles.assign'])
8
9
if not is_admin and not has_permission:
10
raise PermissionError("Insufficient permissions to assign roles")
```
* Go
Verify permissions
```go
1
// Decode JWT and check admin permissions
2
decodedToken, err := decodeJWT(accessToken)
3
if err != nil {
4
return ValidationResult{Success: false, Error: "Invalid token"}
5
}
6
7
// Check if user has admin role or required permissions
8
roles := decodedToken["roles"].([]interface{})
9
permissions := decodedToken["permissions"].([]interface{})
10
11
isAdmin := false
12
hasPermission := false
13
14
for _, role := range roles {
15
if role == "admin" {
16
isAdmin = true
17
break
18
}
19
}
20
21
for _, perm := range permissions {
22
if perm == "users.write" || perm == "roles.assign" {
23
hasPermission = true
24
break
25
}
26
}
27
28
if !isAdmin && !hasPermission {
29
return ValidationResult{Success: false, Error: "Insufficient permissions"}
30
}
```
* Java
Verify permissions
```java
1
// Decode JWT and check admin permissions
2
Claims decodedToken = decodeJWT(accessToken);
3
4
@SuppressWarnings("unchecked")
5
List userRoles = (List) decodedToken.get("roles");
6
@SuppressWarnings("unchecked")
7
List permissions = (List) decodedToken.get("permissions");
8
9
// Check if user has admin role or required permissions
10
boolean isAdmin = userRoles != null && userRoles.contains("admin");
11
boolean hasPermission = permissions != null &&
12
(permissions.contains("users.write") || permissions.contains("roles.assign"));
13
14
if (!isAdmin && !hasPermission) {
15
throw new SecurityException("Insufficient permissions to assign roles");
16
}
```
2. **Collect required identifiers**: Gather the necessary parameters for the API call:
* `user_id`: The unique identifier of the user whose role you’re changing
* `organization_id`: The organization where the role assignment applies
* `roles`: An array of role names to assign to the user
- Node.js
Collect and validate identifiers
```javascript
1
// Structure and validate role assignment data
2
const roleAssignmentData = {
3
user_id: targetUserId,
4
organization_id: targetOrgId,
5
roles: newRoles,
6
// Additional metadata for auditing
7
performed_by: decodedToken.sub,
8
timestamp: new Date().toISOString()
9
};
10
11
// Validate required fields
12
if (!roleAssignmentData.user_id || !roleAssignmentData.organization_id || !roleAssignmentData.roles) {
13
throw new Error('Missing required identifiers for role assignment');
14
}
```
- Python
Collect and validate identifiers
```python
1
# Structure and validate role assignment data
2
role_assignment_data = {
3
'user_id': target_user_id,
4
'organization_id': target_org_id,
5
'roles': new_roles,
6
# Additional metadata for auditing
7
'performed_by': decoded_token.get('sub'),
8
'timestamp': datetime.utcnow().isoformat()
9
}
10
11
# Validate required fields
12
if not all([role_assignment_data['user_id'],
13
role_assignment_data['organization_id'],
14
role_assignment_data['roles']]):
15
raise ValueError("Missing required identifiers for role assignment")
```
- Go
Collect and validate identifiers
```go
1
// Structure and validate role assignment data
2
roleAssignmentData := map[string]interface{}{
3
"user_id": req.UserID,
4
"organization_id": req.OrganizationID,
5
"roles": req.Roles,
6
// Additional metadata for auditing
7
"performed_by": decodedToken["sub"],
8
"timestamp": time.Now().UTC().Format(time.RFC3339),
9
}
10
11
// Validate required fields
12
if req.UserID == "" || req.OrganizationID == "" || len(req.Roles) == 0 {
13
return ValidationResult{Success: false, Error: "Missing required identifiers"}
14
}
```
- Java
Collect and validate identifiers
```java
1
// Structure and validate role assignment data
2
Map roleAssignmentData = new HashMap<>();
3
roleAssignmentData.put("user_id", request.userId);
4
roleAssignmentData.put("organization_id", request.organizationId);
5
roleAssignmentData.put("roles", request.roles);
6
7
// Additional metadata for auditing
8
roleAssignmentData.put("performed_by", decodedToken.getSubject());
9
roleAssignmentData.put("timestamp", Instant.now().toString());
10
11
// Validate required fields
12
if (request.userId == null || request.organizationId == null || request.roles == null) {
13
throw new IllegalArgumentException("Missing required identifiers for role assignment");
14
}
```
3. **Call Scalekit SDK to update user role**: Use the validated data to make the API call that assigns the new roles to the user through the Scalekit membership update endpoint.
* Node.js
Update user role with Scalekit SDK
```javascript
1
// Use case: Update user membership after validation
2
const validationResult = await prepareRoleAssignment(
3
adminAccessToken,
4
targetUserId,
5
targetOrgId,
6
newRoles
7
);
8
9
if (!validationResult.success) {
10
return res.status(403).json({ error: validationResult.error });
11
}
12
13
// Initialize Scalekit client (reference installation guide for setup)
14
const scalekit = new ScalekitClient(
15
process.env.SCALEKIT_ENVIRONMENT_URL,
16
process.env.SCALEKIT_CLIENT_ID,
17
process.env.SCALEKIT_CLIENT_SECRET
18
);
19
20
// Make the API call to update user roles
21
try {
22
const result = await scalekit.user.updateMembership({
23
user_id: validationResult.data.user_id,
24
organization_id: validationResult.data.organization_id,
25
roles: validationResult.data.roles
26
});
27
28
console.log(`Role assigned successfully:`, result);
29
return res.json({
30
success: true,
31
message: "Role updated successfully",
32
data: result
33
});
34
} catch (error) {
35
console.error(`Failed to assign role: ${error.message}`);
36
return res.status(500).json({
37
error: "Failed to update role",
38
details: error.message
39
});
40
}
```
* Python
Update user role with Scalekit SDK
```python
1
# Use case: Update user membership after validation
2
validation_result = prepare_role_assignment(
3
access_token,
4
target_user_id,
5
target_org_id,
6
new_roles
7
)
8
9
if not validation_result['success']:
10
return jsonify({'error': validation_result['error']}), 403
11
12
# Initialize Scalekit client (reference installation guide for setup)
13
scalekit_client = ScalekitClient(
14
env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
15
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
16
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
17
)
18
19
# Make the API call to update user roles
20
try:
21
from scalekit.v1.users.users_pb2 import UpdateMembershipRequest
22
23
request = UpdateMembershipRequest(
24
user_id=validation_result['data']['user_id'],
25
organization_id=validation_result['data']['organization_id'],
26
roles=validation_result['data']['roles']
27
)
28
29
result = scalekit_client.users.update_membership(request=request)
30
print(f"Role assigned successfully: {result}")
31
32
return jsonify({
33
'success': True,
34
'message': 'Role updated successfully',
35
'data': str(result)
36
})
37
38
except Exception as error:
39
print(f"Failed to assign role: {error}")
40
return jsonify({
41
'error': 'Failed to update role',
42
'details': str(error)
43
}), 500
```
* Go
Update user role with Scalekit SDK
```go
1
// Use case: Update user membership after validation
2
validationResult := prepareRoleAssignment(ctx, accessToken, req)
3
4
if !validationResult.Success {
5
http.Error(w, validationResult.Error, http.StatusForbidden)
6
return
7
}
8
9
// Initialize Scalekit client (reference installation guide for setup)
10
scalekitClient := scalekit.NewScalekitClient(
11
os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
12
os.Getenv("SCALEKIT_CLIENT_ID"),
13
os.Getenv("SCALEKIT_CLIENT_SECRET"),
14
)
15
16
// Make the API call to update user roles
17
data := validationResult.Data.(map[string]interface{})
18
updateRequest := &scalekit.UpdateMembershipRequest{
19
UserId: data["user_id"].(string),
20
OrganizationId: data["organization_id"].(string),
21
Roles: data["roles"].([]string),
22
}
23
24
result, err := scalekitClient.Membership().UpdateMembership(ctx, updateRequest)
25
if err != nil {
26
log.Printf("Failed to assign role: %v", err)
27
http.Error(w, "Failed to update role", http.StatusInternalServerError)
28
return
29
}
30
31
log.Printf("Role assigned successfully: %+v", result)
32
json.NewEncoder(w).Encode(map[string]interface{}{
33
"success": true,
34
"message": "Role updated successfully",
35
"data": result,
36
})
```
* Java
Update user role with Scalekit SDK
```java
1
// Use case: Update user membership after validation
2
ValidationResult validationResult = prepareRoleAssignment(accessToken, request);
3
4
if (!validationResult.success) {
5
return ResponseEntity.status(403).body(Map.of("error", validationResult.error));
6
}
7
8
// Initialize Scalekit client (reference installation guide for setup)
9
ScalekitClient scalekitClient = new ScalekitClient(
10
System.getenv("SCALEKIT_ENVIRONMENT_URL"),
11
System.getenv("SCALEKIT_CLIENT_ID"),
12
System.getenv("SCALEKIT_CLIENT_SECRET")
13
);
14
15
// Make the API call to update user roles
16
try {
17
@SuppressWarnings("unchecked")
18
Map data = (Map) validationResult.data;
19
20
UpdateMembershipRequest updateRequest = UpdateMembershipRequest.newBuilder()
21
.setUserId((String) data.get("user_id"))
22
.setOrganizationId((String) data.get("organization_id"))
23
.addAllRoles((List) data.get("roles"))
24
.build();
25
26
UpdateMembershipResponse response = scalekitClient.users().updateMembership(updateRequest);
27
System.out.println("Role assigned successfully: " + response);
28
29
return ResponseEntity.ok(Map.of(
30
"success", true,
31
"message", "Role updated successfully",
32
"data", response.toString()
33
));
34
35
} catch (Exception e) {
36
System.err.println("Failed to assign role: " + e.getMessage());
37
return ResponseEntity.status(500).body(Map.of(
38
"error", "Failed to update role",
39
"details", e.getMessage()
40
));
41
}
```
4. **Handle response and provide feedback**: Return appropriate success/error responses to the administrator and update your application’s UI accordingly.
* Node.js
Handle API response
```javascript
1
// Success response handling
2
if (result.success) {
3
// Update UI to reflect role change
4
await updateUserInterface(targetUserId, newRoles);
5
6
// Send notification to user (optional)
7
await notifyUserOfRoleChange(targetUserId, newRoles);
8
9
// Log the action for audit purposes
10
await logRoleChange({
11
performed_by: decodedToken.sub,
12
target_user: targetUserId,
13
organization: targetOrgId,
14
old_roles: previousRoles,
15
new_roles: newRoles,
16
timestamp: new Date().toISOString()
17
});
18
}
```
* Python
Handle API response
```python
1
# Success response handling
2
if result.get('success'):
3
# Update UI to reflect role change
4
await update_user_interface(target_user_id, new_roles)
5
6
# Send notification to user (optional)
7
await notify_user_of_role_change(target_user_id, new_roles)
8
9
# Log the action for audit purposes
10
await log_role_change({
11
'performed_by': decoded_token.get('sub'),
12
'target_user': target_user_id,
13
'organization': target_org_id,
14
'old_roles': previous_roles,
15
'new_roles': new_roles,
16
'timestamp': datetime.utcnow().isoformat()
17
})
```
* Go
Handle API response
```go
1
// Success response handling
2
if success {
3
// Update UI to reflect role change
4
updateUserInterface(targetUserID, newRoles)
5
6
// Send notification to user (optional)
7
notifyUserOfRoleChange(targetUserID, newRoles)
8
9
// Log the action for audit purposes
10
logRoleChange(map[string]interface{}{
11
"performed_by": decodedToken["sub"],
12
"target_user": targetUserID,
13
"organization": targetOrgID,
14
"old_roles": previousRoles,
15
"new_roles": newRoles,
16
"timestamp": time.Now().UTC().Format(time.RFC3339),
17
})
18
}
```
* Java
Handle API response
```java
1
// Success response handling
2
if (response.getBody().containsKey("success") &&
3
Boolean.TRUE.equals(response.getBody().get("success"))) {
4
5
// Update UI to reflect role change
6
updateUserInterface(targetUserId, newRoles);
7
8
// Send notification to user (optional)
9
notifyUserOfRoleChange(targetUserId, newRoles);
10
11
// Log the action for audit purposes
12
logRoleChange(Map.of(
13
"performed_by", decodedToken.getSubject(),
14
"target_user", targetUserId,
15
"organization", targetOrgId,
16
"old_roles", previousRoles,
17
"new_roles", newRoles,
18
"timestamp", Instant.now().toString()
19
));
20
}
```
---
# DOCUMENT BOUNDARY
---
# Create and manage roles and permissions
> Set up roles and permissions to control access in your application
Before writing any code, take a moment to plan your application’s authorization model. A well-designed structure for roles and permissions is crucial for security and maintainability. Start by considering the following questions:
* What are the actions your users can perform?
* How many distinct roles does your application need?
Your application’s use cases will determine the answers. Here are a few common patterns:
* **Simple roles**: Some applications, like an online whiteboarding tool, may only need a few roles with implicit permissions. For example, `Admin`, `Editor`, and `Viewer`. In this case, you might not even need to define granular permissions.
* **Pre-defined roles and permissions**: Many applications have a fixed set of roles built from specific permissions. For a project management tool, you could define permissions like `projects:create` and `tasks:assign`, then group them into roles like `Project Manager` and `Team Member`.
* **Customer-defined Roles**: For complex applications, you might allow organization owners to create custom roles with a specific set of permissions. These roles are specific to an organization rather than global to your application.
Scalekit provides the flexibility to build authorization for any of these use cases. Once you have a clear plan, you can start creating your permissions and roles.
Define the permissions your application needs by registering them with Scalekit. Use the `resource:action` format for clear, self-documenting permission names. You can skip this step, in case permissions may not fit your app’s authorization model.
1. ## Define the actions your users can perform as permissions
[Section titled “Define the actions your users can perform as permissions”](#define-the-actions-your-users-can-perform-as-permissions)
* Node.js
Create permissions
```javascript
9 collapsed lines
1
// Initialize Scalekit client
2
// Use case: Register all available actions in your project management app
3
import { ScalekitClient } from "@scalekit-sdk/node";
4
5
const scalekit = new ScalekitClient(
6
process.env.SCALEKIT_ENVIRONMENT_URL,
7
process.env.SCALEKIT_CLIENT_ID,
8
process.env.SCALEKIT_CLIENT_SECRET
9
);
10
11
// Define your application's permissions
12
const permissions = [
13
{
14
name: "projects:create",
15
description: "Allows users to create new projects"
16
},
17
{
18
name: "projects:read",
19
description: "Allows users to view project details"
20
},
21
{
22
name: "projects:update",
23
description: "Allows users to modify existing projects"
24
},
25
{
26
name: "projects:delete",
27
description: "Allows users to remove projects"
28
},
29
{
30
name: "tasks:assign",
31
description: "Allows users to assign tasks to team members"
32
}
33
];
34
35
// Register each permission with Scalekit
36
for (const permission of permissions) {
37
await scalekit.permission.createPermission(permission);
38
console.log(`Created permission: ${permission.name}`);
39
}
40
41
// Your application's permissions are now registered with Scalekit
```
* Python
Create permissions
```python
12 collapsed lines
1
# Initialize Scalekit client
2
# Use case: Register all available actions in your project management app
3
from scalekit import ScalekitClient
4
5
scalekit_client = ScalekitClient(
6
env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
7
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
8
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
9
)
10
11
# Define your application's permissions
12
from scalekit.v1.roles.roles_pb2 import CreatePermission
13
14
permissions = [
15
CreatePermission(
16
name="projects:create",
17
description="Allows users to create new projects"
18
),
19
CreatePermission(
20
name="projects:read",
21
description="Allows users to view project details"
22
),
23
CreatePermission(
24
name="projects:update",
25
description="Allows users to modify existing projects"
26
),
27
CreatePermission(
28
name="projects:delete",
29
description="Allows users to remove projects"
30
),
31
CreatePermission(
32
name="tasks:assign",
33
description="Allows users to assign tasks to team members"
34
)
35
]
36
37
# Register each permission with Scalekit
38
for permission in permissions:
39
scalekit_client.permissions.create_permission(permission=permission)
40
print(f"Created permission: {permission.name}")
41
42
# Your application's permissions are now registered with Scalekit
```
* Go
Create permissions
```go
17 collapsed lines
1
// Initialize Scalekit client
2
// Use case: Register all available actions in your project management app
3
package main
4
5
import (
6
"context"
7
"log"
8
"github.com/scalekit-inc/scalekit-sdk-go"
9
)
10
11
func main() {
12
sc := scalekit.NewScalekitClient(
13
os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
14
os.Getenv("SCALEKIT_CLIENT_ID"),
15
os.Getenv("SCALEKIT_CLIENT_SECRET"),
16
)
17
18
// Define your application's permissions
19
permissions := []*scalekit.CreatePermission{
20
{
21
Name: "projects:create",
22
Description: "Allows users to create new projects",
23
},
24
{
25
Name: "projects:read",
26
Description: "Allows users to view project details",
27
},
28
{
29
Name: "projects:update",
30
Description: "Allows users to modify existing projects",
31
},
32
{
33
Name: "projects:delete",
34
Description: "Allows users to remove projects",
35
},
36
{
37
Name: "tasks:assign",
38
Description: "Allows users to assign tasks to team members",
39
},
40
}
41
42
// Register each permission with Scalekit
43
for _, permission := range permissions {
44
_, err := sc.Permission().CreatePermission(ctx, permission)
45
if err != nil {
46
log.Printf("Failed to create permission: %s", permission.Name)
47
continue
48
}
49
fmt.Printf("Created permission: %s\n", permission.Name)
50
}
51
52
// Your application's permissions are now registered with Scalekit
53
}
```
* Java
Create permissions
```java
11 collapsed lines
1
// Initialize Scalekit client
2
// Use case: Register all available actions in your project management app
3
import com.scalekit.ScalekitClient;
4
import com.scalekit.grpc.scalekit.v1.roles.*;
5
6
ScalekitClient scalekitClient = new ScalekitClient(
7
System.getenv("SCALEKIT_ENVIRONMENT_URL"),
8
System.getenv("SCALEKIT_CLIENT_ID"),
9
System.getenv("SCALEKIT_CLIENT_SECRET")
10
);
11
12
// Define your application's permissions
13
List permissions = Arrays.asList(
14
CreatePermission.newBuilder()
15
.setName("projects:create")
16
.setDescription("Allows users to create new projects")
17
.build(),
18
CreatePermission.newBuilder()
19
.setName("projects:read")
20
.setDescription("Allows users to view project details")
21
.build(),
22
CreatePermission.newBuilder()
23
.setName("projects:update")
24
.setDescription("Allows users to modify existing projects")
25
.build(),
26
CreatePermission.newBuilder()
27
.setName("projects:delete")
28
.setDescription("Allows users to remove projects")
29
.build(),
30
CreatePermission.newBuilder()
31
.setName("tasks:assign")
32
.setDescription("Allows users to assign tasks to team members")
33
.build()
34
);
35
36
// Register each permission with Scalekit
37
for (CreatePermission permission : permissions) {
38
try {
39
CreatePermissionRequest request = CreatePermissionRequest.newBuilder()
40
.setPermission(permission)
41
.build();
42
43
scalekitClient.permissions().createPermission(request);
44
System.out.println("Created permission: " + permission.getName());
45
} catch (Exception e) {
46
System.err.println("Error creating permission: " + e.getMessage());
47
}
48
}
49
50
// Your application's permissions are now registered with Scalekit
```
2. ## Register roles your applications will use
[Section titled “Register roles your applications will use”](#register-roles-your-applications-will-use)
Once you have defined permissions, group them into roles that match your application’s access patterns.
* Node.js
Create roles with permissions
```javascript
1
// Define roles with their associated permissions
2
// Use case: Create standard roles for your project management application
3
const roles = [
4
{
5
name: 'project_admin',
6
display_name: 'Project Administrator',
7
description: 'Full access to manage projects and team members',
8
permissions: [
9
'projects:create', 'projects:read', 'projects:update', 'projects:delete',
10
'tasks:assign'
11
]
12
},
13
{
14
name: 'project_manager',
15
display_name: 'Project Manager',
16
description: 'Can manage projects and assign tasks',
17
permissions: [
18
'projects:create', 'projects:read', 'projects:update',
19
'tasks:assign'
20
]
21
},
22
{
23
name: 'team_member',
24
display_name: 'Team Member',
25
description: 'Can view projects and participate in tasks',
26
permissions: [
27
'projects:read'
28
]
29
}
30
];
31
32
// Register each role with Scalekit
33
for (const role of roles) {
34
await scalekit.role.createRole(role);
35
console.log(`Created role: ${role.name}`);
36
}
37
38
// Your application's roles are now registered with Scalekit
```
* Python
Create roles with permissions
```python
1
# Define roles with their associated permissions
2
# Use case: Create standard roles for your project management application
3
from scalekit.v1.roles.roles_pb2 import CreateRole
4
5
roles = [
6
CreateRole(
7
name="project_admin",
8
display_name="Project Administrator",
9
description="Full access to manage projects and team members",
10
permissions=["projects:create", "projects:read", "projects:update", "projects:delete", "tasks:assign"]
11
),
12
CreateRole(
13
name="project_manager",
14
display_name="Project Manager",
15
description="Can manage projects and assign tasks",
16
permissions=["projects:create", "projects:read", "projects:update", "tasks:assign"]
17
),
18
CreateRole(
19
name="team_member",
20
display_name="Team Member",
21
description="Can view projects and participate in tasks",
22
permissions=["projects:read"]
23
)
24
]
25
26
# Register each role with Scalekit
27
for role in roles:
28
scalekit_client.roles.create_role(role=role)
29
print(f"Created role: {role.name}")
30
31
# Your application's roles are now registered with Scalekit
```
* Go
Create roles with permissions
```go
1
// Define roles with their associated permissions
2
// Use case: Create standard roles for your project management application
3
roles := []*scalekit.CreateRole{
4
{
5
Name: "project_admin",
6
DisplayName: "Project Administrator",
7
Description: "Full access to manage projects and team members",
8
Permissions: []string{"projects:create", "projects:read", "projects:update", "projects:delete", "tasks:assign"},
9
},
10
{
11
Name: "project_manager",
12
DisplayName: "Project Manager",
13
Description: "Can manage projects and assign tasks",
14
Permissions: []string{"projects:create", "projects:read", "projects:update", "tasks:assign"},
15
},
16
{
17
Name: "team_member",
18
DisplayName: "Team Member",
19
Description: "Can view projects and participate in tasks",
20
Permissions: []string{"projects:read"},
21
},
22
}
23
24
// Register each role with Scalekit
25
for _, role := range roles {
26
_, err := sc.Role().CreateRole(ctx, role)
27
if err != nil {
28
log.Printf("Failed to create role: %s", role.Name)
29
continue
30
}
31
fmt.Printf("Created role: %s\n", role.Name)
32
}
33
34
// Your application's roles are now registered with Scalekit
```
* Java
Create roles with permissions
```java
1
// Define roles with their associated permissions
2
// Use case: Create standard roles for your project management application
3
List roles = Arrays.asList(
4
CreateRole.newBuilder()
5
.setName("project_admin")
6
.setDisplayName("Project Administrator")
7
.setDescription("Full access to manage projects and team members")
8
.addAllPermissions(Arrays.asList("projects:create", "projects:read", "projects:update", "projects:delete", "tasks:assign"))
9
.build(),
10
CreateRole.newBuilder()
11
.setName("project_manager")
12
.setDisplayName("Project Manager")
13
.setDescription("Can manage projects and assign tasks")
14
.addAllPermissions(Arrays.asList("projects:create", "projects:read", "projects:update", "tasks:assign"))
15
.build(),
16
CreateRole.newBuilder()
17
.setName("team_member")
18
.setDisplayName("Team Member")
19
.setDescription("Can view projects and participate in tasks")
20
.addPermissions("projects:read")
21
.build()
22
);
23
24
// Register each role with Scalekit
25
for (CreateRole role : roles) {
26
try {
27
CreateRoleRequest request = CreateRoleRequest.newBuilder()
28
.setRole(role)
29
.build();
30
31
scalekitClient.roles().createRole(request);
32
System.out.println("Created role: " + role.getName());
33
} catch (Exception e) {
34
System.err.println("Error creating role: " + e.getMessage());
35
}
36
}
37
38
// Your application's roles are now registered with Scalekit
```
## Inherit permissions through roles
[Section titled “Inherit permissions through roles”](#inherit-permissions-through-roles)
Large applications with extensive feature sets require sophisticated role and permission management. Scalekit enables role inheritance, allowing you to create a hierarchical access control system. Permissions can be grouped into roles, and new roles can be derived from existing base roles, providing a flexible and scalable approach to defining user access.
Role assignment in Scalekit automatically grants a user all permissions defined within that role.
This is how you can implement use it:
1. Your app defines the permissions and assigns to a role. Let’s say `viewer` role.
2. When creating new role called `editor`, you specify that it inherits the permissions from the `viewer` role.
3. When creating new role called `project_owner`, you specify that it inherits the permissions from the `editor` role.
Take a look at our [Roles and Permissions APIs](https://docs.scalekit.com/apis/#tag/roles/GET/api/v1/roles).
## Manage roles and permissions in the dashboard
[Section titled “Manage roles and permissions in the dashboard”](#manage-roles-and-permissions-in-the-dashboard)
For most applications, the simplest way to create and manage roles and permissions is through the Scalekit dashboard. This approach works well when you have a fixed set of roles and permissions that don’t need to be modified by users in your application. You can set up your authorization model once during application configuration and manage it through the dashboard going forward.
1. Navigate to **Dashboard** > **Roles & Permissions** > **Permissions** to create permissions:
* Click **Create Permission** and provide:
* **Name** - Machine-friendly identifier (e.g., `projects:create`)
* **Display Name** - Human-readable label (e.g., “Create Projects”)
* **Description** - Clear explanation of what this permission allows
2. Go to **Dashboard** > **Roles & Permissions** > **Roles** to create roles:
* Click **Create Role** and provide:
* **Name** - Machine-friendly identifier (e.g., `project_manager`)
* **Display Name** - Human-readable label (e.g., “Project Manager”)
* **Description** - Clear explanation of the role’s purpose
* **Permissions** - Select the permissions to include in this role
3. Configure default roles for new users who join organizations
4. Organization administrators can create organization-specific roles by going to **Dashboard** > **Organizations** > **Select organization** > **Roles**
Now that you have created roles and permissions in Scalekit, the next step is to assign these roles to users in your application.
### Configure organization specific roles
[Section titled “Configure organization specific roles”](#configure-organization-specific-roles)
Organization-level roles let organization administrators create custom roles that apply only within their specific organization. These roles are separate from any application-level roles you define.
You can create organization-level roles from the Scalekit Dashboard:
* Go to **Organizations → Select an organization → Roles**
* In **Organization roles** section, Click **+ Add role** and provide:
* **Display name**: Human-readable name (e.g., “Manager”)
* **Name (key)**: Machine-friendly identifier (e.g., `manager`)
* **Description**: Clear explanation of what users with this role can do
---
# DOCUMENT BOUNDARY
---
# Implement access control
> Verify permissions and roles in your application code to control user access
After configuring permissions and roles, the next critical step is implementing access control directly within your application code. This is achieved by carefully examining the roles and permissions embedded in the user’s access token to make authorization decisions.
Scalekit conveniently packages these authorization details during the authentication process, providing you with a comprehensive set of data to make precise access control decisions without requiring additional API calls.
Review the authorization flow
This section focuses on implementing access control, which naturally follows user authentication. We recommend completing the authentication [quickstart](/authenticate/fsa/quickstart) before diving into these access control implementation details.
## Start by inspecting the access token
[Section titled “Start by inspecting the access token”](#start-by-inspecting-the-access-token)
When you [exchange the code for a user profile](/authenticate/fsa/complete-login/), Scalekit also adds additional information that help your app determine the access control decisions.
* Auth result
```js
1
{
2
user: {
3
email: "john.doe@example.com",
4
emailVerified: true,
5
givenName: "John",
6
name: "John Doe",
7
id: "usr_74599896446906854"
8
},
9
idToken: "eyJhbGciO..", // Decode for full user details
10
11
accessToken: "eyJhbGciOi..",
12
refreshToken: "rt_8f7d6e5c4b3a2d1e0f9g8h7i6j..",
13
expiresIn: 299 // in seconds
14
}
```
* Decoded ID token
ID token decoded
```json
1
{
2
"at_hash": "ec_jU2ZKpFelCKLTRWiRsg",
3
"aud": [
4
"skc_58327482062864390"
5
],
6
"azp": "skc_58327482062864390",
7
"c_hash": "6wMreK9kWQQY6O5R0CiiYg",
8
"client_id": "skc_58327482062864390",
9
"email": "john.doe@example.com",
10
"email_verified": true,
11
"exp": 1742975822,
12
"family_name": "Doe",
13
"given_name": "John",
14
"iat": 1742974022,
15
"iss": "https://scalekit-z44iroqaaada-dev.scalekit.cloud",
16
"name": "John Doe",
17
"oid": "org_59615193906282635",
18
"sid": "ses_65274187031249433",
19
"sub": "usr_63261014140912135"
20
}
```
* Decoded access token
Decoded access token
```json
1
{
2
"aud": [
3
"prd_skc_7848964512134X699"
4
],
5
"client_id": "prd_skc_7848964512134X699",
6
"exp": 1758265247,
7
"iat": 1758264947,
8
"iss": "https://login.devramp.ai",
9
"jti": "tkn_90928731115292X63",
10
"nbf": 1758264947,
11
"oid": "org_89678001X21929734",
12
"permissions": [
13
"workspace_data:write",
14
"workspace_data:read"
15
],
16
"roles": [
17
"admin"
18
],
19
"sid": "ses_90928729571723X24",
20
"sub": "usr_8967800122X995270",
21
// External identifiers if updated on Scalekit
22
"xoid": "ext_org_123", // Organization ID
23
"xuid": "ext_usr_456", // User ID
24
}
```
Let’s closely look at the access token:
Decoded access token
```json
{
"aud": ["skc_987654321098765432"],
"client_id": "skc_987654321098765432",
"exp": 1750850145,
"iat": 1750849845,
"iss": "http://example.localhost:8889",
"jti": "tkn_987654321098765432",
"nbf": 1750849845,
"roles": ["project_manager", "member"],
"oid": "org_69615647365005430",
"permissions": ["projects:create", "projects:read", "projects:update", "tasks:assign"],
"sid": "ses_987654321098765432",
"sub": "usr_987654321098765432"
}
```
The `roles` and `permissions` values provide runtime insights into the user’s access constraints directly within the access token, eliminating the need for additional API requests. Crucially, always validate the token’s integrity before relying on the embedded authorization details.
* Node.js
Validate and decode access token in middleware
```javascript
1
// Middleware to validate tokens and extract authorization data
2
const validateAndExtractAuth = async (req, res, next) => {
3
try {
4
// Extract access token from cookie (decrypt if needed)
5
const accessToken = decrypt(req.cookies.accessToken);
6
7
// Validate the token using Scalekit SDK
8
const isValid = await scalekit.validateAccessToken(accessToken);
9
10
if (!isValid) {
11
return res.status(401).json({ error: 'Invalid or expired token' });
12
}
13
14
// Decode token to get roles and permissions using any JWT decode library
15
const tokenData = await decodeAccessToken(accessToken);
16
17
// Make authorization data available to route handlers
18
req.user = {
19
id: tokenData.sub,
20
organizationId: tokenData.oid,
21
roles: tokenData.roles || [],
22
permissions: tokenData.permissions || []
23
};
24
25
next();
26
} catch (error) {
27
return res.status(401).json({ error: 'Authentication failed' });
28
}
29
};
```
* Python
Validate and decode access token
```python
4 collapsed lines
1
from scalekit import ScalekitClient
2
from functools import wraps
3
import jwt
4
5
scalekit_client = ScalekitClient(/* your credentials */)
6
7
def validate_and_extract_auth(f):
8
@wraps(f)
9
def decorated_function(*args, **kwargs):
10
try:
11
# Extract access token from cookie (decrypt if needed)
12
access_token = decrypt(request.cookies.get('accessToken'))
13
14
# Validate the token using Scalekit SDK
15
is_valid = scalekit_client.validate_access_token(access_token)
16
17
if not is_valid:
18
return jsonify({'error': 'Invalid or expired token'}), 401
19
20
# Decode token to get roles and permissions
21
token_data = scalekit_client.decode_access_token(access_token)
22
23
# Make authorization data available to route handlers
24
request.user = {
25
'id': token_data.get('sub'),
26
'organization_id': token_data.get('oid'),
27
'roles': token_data.get('roles', []),
28
'permissions': token_data.get('permissions', [])
29
}
30
31
return f(*args, **kwargs)
32
except Exception as e:
33
return jsonify({'error': 'Authentication failed'}), 401
34
35
return decorated_function
```
* Go
Validate and decode access token
```go
7 collapsed lines
1
import (
2
"context"
3
"encoding/json"
4
"net/http"
5
"github.com/scalekit-inc/scalekit-sdk-go"
6
)
7
8
scalekitClient := scalekit.NewScalekitClient(/* your credentials */)
9
10
func validateAndExtractAuth(next http.HandlerFunc) http.HandlerFunc {
11
return func(w http.ResponseWriter, r *http.Request) {
12
// Extract access token from cookie (decrypt if needed)
13
cookie, err := r.Cookie("accessToken")
14
if err != nil {
15
http.Error(w, `{"error": "No access token provided"}`, http.StatusUnauthorized)
16
return
17
}
18
19
accessToken, err := decrypt(cookie.Value)
20
if err != nil {
21
http.Error(w, `{"error": "Token decryption failed"}`, http.StatusUnauthorized)
22
return
23
}
24
25
// Validate the token using Scalekit SDK
26
isValid, err := scalekitClient.ValidateAccessToken(r.Context(), accessToken)
27
if err != nil || !isValid {
28
http.Error(w, `{"error": "Invalid or expired token"}`, http.StatusUnauthorized)
29
return
30
}
31
32
// Decode token to get roles and permissions using any JWT decode lib
33
tokenData, err := DecodeAccessToken(accessToken)
34
if err != nil {
35
http.Error(w, `{"error": "Token decode failed"}`, http.StatusUnauthorized)
36
return
37
}
38
39
// Add authorization data to request context
40
user := map[string]interface{}{
41
"id": tokenData["sub"],
42
"organization_id": tokenData["oid"],
43
"roles": tokenData["roles"],
44
"permissions": tokenData["permissions"],
45
}
46
47
ctx := context.WithValue(r.Context(), "user", user)
48
next(w, r.WithContext(ctx))
49
}
50
}
```
* Java
Validate and decode access token
```java
7 collapsed lines
1
import com.scalekit.ScalekitClient;
2
import javax.servlet.http.HttpServletRequest;
3
import javax.servlet.http.HttpServletResponse;
4
import org.springframework.web.servlet.HandlerInterceptor;
5
import java.util.Map;
6
import java.util.HashMap;
7
8
@Component
9
public class AuthorizationInterceptor implements HandlerInterceptor {
10
private final ScalekitClient scalekit;
11
12
@Override
13
public boolean preHandle(
14
HttpServletRequest request,
15
HttpServletResponse response,
16
Object handler
17
) throws Exception {
18
try {
19
// Extract access token from cookie (decrypt if needed)
20
String accessToken = getCookieValue(request, "accessToken");
21
String decryptedToken = decrypt(accessToken);
22
23
// Validate the token using Scalekit SDK
24
boolean isValid = scalekit.authentication().validateAccessToken(decryptedToken);
25
26
if (!isValid) {
27
response.setStatus(HttpStatus.UNAUTHORIZED.value());
28
response.getWriter().write("{\"error\": \"Invalid or expired token\"}");
29
return false;
30
}
31
32
// Decode token to get roles and permissions using any JWT decode lib
33
Map tokenData = decodeAccessToken(decryptedToken);
34
35
// Make authorization data available to controllers
36
Map user = new HashMap<>();
37
user.put("id", tokenData.get("sub"));
38
user.put("organizationId", tokenData.get("oid"));
39
user.put("roles", tokenData.get("roles"));
40
user.put("permissions", tokenData.get("permissions"));
41
42
request.setAttribute("user", user);
43
return true;
44
45
} catch (Exception e) {
46
response.setStatus(HttpStatus.UNAUTHORIZED.value());
47
response.getWriter().write("{\"error\": \"Authentication failed\"}");
48
return false;
49
}
50
}
51
}
```
This approach makes user roles and permissions available throughout different routes of your application, enabling consistent and secure access control across all endpoints.
## Verify user’s role to allow access to protected resources
[Section titled “Verify user’s role to allow access to protected resources”](#verify-users-role-to-allow-access-to-protected-resources)
Role-based access control (RBAC) provides a straightforward way to manage permissions by grouping them into logical roles. Instead of checking individual permissions for every action, your application can simply verify if the user has the required role, making access control decisions more efficient and easier to maintain.
Tip
Use roles for broad access control patterns like admin access, management privileges, or user tiers. Reserve permissions for fine-grained control over specific actions and resources.
* Node.js
Role-based access control
```javascript
17 collapsed lines
1
// Helper function to check roles
2
function hasRole(user, requiredRole) {
3
return user.roles && user.roles.includes(requiredRole);
4
}
5
6
// Middleware to require specific roles
7
function requireRole(role) {
8
return (req, res, next) => {
9
if (!hasRole(req.user, role)) {
10
return res.status(403).json({
11
error: `Access denied. Required role: ${role}`
12
});
13
}
14
next();
15
};
16
}
17
18
// Admin-only routes
19
app.get('/api/admin/users', validateAndExtractAuth, requireRole('admin'), (req, res) => {
20
// Only admin users can access this endpoint
21
res.json(getAllUsers(req.user.organizationId));
22
});
23
24
// Multiple role check
25
app.post('/api/admin/invite-user', validateAndExtractAuth, (req, res) => {
26
const user = req.user;
27
28
// Allow admins or managers to invite users
29
if (!hasRole(user, 'admin') && !hasRole(user, 'manager')) {
30
return res.status(403).json({ error: 'Only admins and managers can invite users' });
31
}
32
33
const invitation = createUserInvitation(req.body, user.organizationId);
34
res.json(invitation);
35
});
```
* Python
Role-based access control
```python
17 collapsed lines
1
# Helper function to check roles
2
def has_role(user, required_role):
3
roles = user.get('roles', [])
4
return required_role in roles
5
6
# Decorator to require specific roles
7
def require_role(role):
8
def decorator(f):
9
@wraps(f)
10
def decorated_function(*args, **kwargs):
11
user = getattr(request, 'user', {})
12
if not has_role(user, role):
13
return jsonify({'error': f'Access denied. Required role: {role}'}), 403
14
return f(*args, **kwargs)
15
return decorated_function
16
return decorator
17
18
# Admin-only routes
19
@app.route('/api/admin/users')
20
@validate_and_extract_auth
21
@require_role('admin')
22
def get_all_users():
23
# Only admin users can access this endpoint
24
return jsonify(get_all_users_for_org(request.user['organization_id']))
25
26
# Multiple role check
27
@app.route('/api/admin/invite-user', methods=['POST'])
28
@validate_and_extract_auth
29
def invite_user():
30
user = request.user
31
32
# Allow admins or managers to invite users
33
if not has_role(user, 'admin') and not has_role(user, 'manager'):
34
return jsonify({'error': 'Only admins and managers can invite users'}), 403
35
36
invitation = create_user_invitation(request.json, user['organization_id'])
37
return jsonify(invitation)
```
* Go
Role-based access control
```go
31 collapsed lines
1
// Helper function to check roles
2
func hasRole(user map[string]interface{}, requiredRole string) bool {
3
roles, ok := user["roles"].([]interface{})
4
if !ok {
5
return false
6
}
7
8
for _, role := range roles {
9
if roleStr, ok := role.(string); ok && roleStr == requiredRole {
10
return true
11
}
12
}
13
return false
14
}
15
16
// Middleware to require specific roles
17
func requireRole(role string) func(http.HandlerFunc) http.HandlerFunc {
18
return func(next http.HandlerFunc) http.HandlerFunc {
19
return func(w http.ResponseWriter, r *http.Request) {
20
user := r.Context().Value("user").(map[string]interface{})
21
22
if !hasRole(user, role) {
23
http.Error(w, fmt.Sprintf(`{"error": "Access denied. Required role: %s"}`, role), http.StatusForbidden)
24
return
25
}
26
27
next(w, r)
28
}
29
}
30
}
31
32
// Admin-only routes
33
func getAllUsersHandler(w http.ResponseWriter, r *http.Request) {
34
user := r.Context().Value("user").(map[string]interface{})
35
orgId := user["organization_id"].(string)
36
37
// Only admin users can access this endpoint
38
users := getAllUsersForOrg(orgId)
39
json.NewEncoder(w).Encode(users)
40
}
41
42
// Route setup with role middleware
43
http.HandleFunc("/api/admin/users", validateAndExtractAuth(requireRole("admin")(getAllUsersHandler)))
```
* Java
Role-based access control
```java
1
@RestController
2
public class AdminController {
7 collapsed lines
3
4
// Helper method to check roles
5
private boolean hasRole(Map user, String requiredRole) {
6
List roles = (List) user.get("roles");
7
return roles != null && roles.contains(requiredRole);
8
}
9
10
// Admin-only endpoint
11
@GetMapping("/api/admin/users")
12
public ResponseEntity