for critical issues
## Next steps
[Section titled “Next steps”](#next-steps)
* [Scopes and Permissions](/agent-auth/authentication/scopes-permissions) - Managing OAuth scopes
* [Multi-Provider Authentication](/agent-auth/authentication/multi-provider) - Managing multiple connections
---
# DOCUMENT BOUNDARY
---
# Auth patterns
> Learn the supported auth types, provider payload fields, and auth pattern configuration used by bring your own provider.
Auth patterns define how Scalekit should authenticate to the upstream API.
Use this page to choose an auth type and build the provider payload for a custom provider.
## Choose an auth type
[Section titled “Choose an auth type”](#choose-an-auth-type)
Bring your own provider supports these auth types:
* OAUTH
* BASIC
* BEARER
* API\_KEY
Use OAUTH when the upstream API requires a user authorization flow and token exchange. Use BASIC, BEARER, or API\_KEY when the upstream API accepts static credentials or long-lived tokens that Scalekit can attach during proxy calls.
## Understand the provider payload
[Section titled “Understand the provider payload”](#understand-the-provider-payload)
The provider payload uses these common top-level fields:
* `display_name`: Human-readable name for the custom provider
* `description`: Short description of what the provider connects to
* `auth_patterns`: Authentication options supported by the provider
* `proxy_url`: Base URL the proxy should call for the upstream API (mandatory)
* `proxy_enabled`: Whether the proxy is enabled for the provider (mandatory, should be true)
`proxy_url` can also include templated fields when the upstream API requires account-specific values, for example `https://{{domain}}/api`.
## Understand auth pattern fields
[Section titled “Understand auth pattern fields”](#understand-auth-pattern-fields)
Within `auth_patterns`, the most common fields are:
* `type`: The auth type, such as OAUTH, BASIC, BEARER, or API\_KEY
* `display_name`: Label shown for that auth option
* `description`: Short explanation of the auth method
* `fields`: Inputs collected for static auth providers such as BASIC, BEARER, and API\_KEY. These usually store values such as `username`, `password`, `token`, `api_key`, `domain`, or `version`.
* `account_fields`: Inputs collected for OAUTH providers when account-scoped values are needed. This is typically used for values tied to a connected account, such as named path parameters.
* `oauth_config`: OAuth-specific configuration, such as authorize and token endpoints
* `auth_header_key_override`: Custom header name when the upstream does not use `Authorization`. For example, some APIs expect auth in a header such as `X-API-Key` instead of the standard `Authorization` header.
* `auth_field_mutations`: Value transformations applied before the credential is sent. This is useful when the upstream expects a prefix, suffix, or default companion value, such as adding a token prefix or setting a fallback password value for Basic auth.
These fields control how Scalekit collects credentials and applies them during proxy calls.
## Example JSON payloads
[Section titled “Example JSON payloads”](#example-json-payloads)
Use a payload like the following based on the auth pattern you need. In the management flow, you can pass these JSON bodies into the appropriate create or update request.
* OAuth
```json
1
{
2
"display_name": "My Asana",
3
"description": "Connect to Asana. Manage tasks, projects, teams, and workflow automation",
4
"auth_patterns": [
5
{
6
"type": "OAUTH",
7
"display_name": "OAuth 2.0",
8
"description": "Authenticate with Asana using OAuth 2.0 for comprehensive project management",
9
"fields": [],
10
"oauth_config": {
11
"authorize_uri": "https://app.asana.com/-/oauth_authorize",
12
"token_uri": "https://app.asana.com/-/oauth_token",
13
"user_info_uri": "https://app.asana.com/api/1.0/users/me",
14
"available_scopes": [
15
{
16
"scope": "profile",
17
"display_name": "Profile",
18
"description": "Access user profile information",
19
"required": true
20
},
21
{
22
"scope": "email",
23
"display_name": "Email",
24
"description": "Access user email address",
25
"required": true
26
}
27
]
28
}
29
}
30
],
31
"proxy_url": "https://app.asana.com/api",
32
"proxy_enabled": true
33
}
```
* Bearer
```json
1
{
2
"display_name": "My Bearer Token Provider",
3
"description": "Connect to an API that accepts a static bearer token",
4
"auth_patterns": [
5
{
6
"type": "BEARER",
7
"display_name": "Bearer Token",
8
"description": "Authenticate with a static bearer token",
9
"fields": [
10
{
11
"field_name": "token",
12
"label": "Bearer Token",
13
"input_type": "password",
14
"hint": "Your long-lived bearer token",
15
"required": true
16
}
17
]
18
}
19
],
20
"proxy_url": "https://api.example.com",
21
"proxy_enabled": true
22
}
```
* Basic
```json
1
{
2
"display_name": "My Freshdesk",
3
"description": "Connect to Freshdesk. Manage tickets, contacts, companies, and customer support workflows",
4
"auth_patterns": [
5
{
6
"type": "BASIC",
7
"display_name": "Basic Auth",
8
"description": "Authenticate with Freshdesk using Basic Auth with username and password for comprehensive helpdesk management",
9
"fields": [
10
{
11
"field_name": "domain",
12
"label": "Freshdesk Domain",
13
"input_type": "text",
14
"hint": "Your Freshdesk domain (e.g., yourcompany.freshdesk.com)",
15
"required": true
16
},
17
{
18
"field_name": "username",
19
"label": "API Key",
20
"input_type": "text",
21
"hint": "Your Freshdesk API Key",
22
"required": true
23
}
24
]
25
}
26
],
27
"proxy_url": "https://{{domain}}/api",
28
"proxy_enabled": true
29
}
```
* API Key
```json
1
{
2
"display_name": "My Attention",
3
"description": "Connect to Attention for AI insights, conversations, teams, and workflows",
4
"auth_patterns": [
5
{
6
"type": "API_KEY",
7
"display_name": "API Key",
8
"description": "Authenticate with Attention using an API Key",
9
"fields": [
10
{
11
"field_name": "api_key",
12
"label": "Integration Token",
13
"input_type": "password",
14
"hint": "Your Attention API Key",
15
"required": true
16
}
17
]
18
}
19
],
20
"proxy_url": "https://api.attention.tech",
21
"proxy_enabled": true
22
}
```
## Review the final payload carefully
[Section titled “Review the final payload carefully”](#review-the-final-payload-carefully)
When you review the final payload, pay close attention to:
* `display_name` and `description`
* The selected auth `type`
* Required `fields` and `account_fields`
* OAuth endpoints and scopes, if the provider uses OAuth
* `proxy_url`
Use the payload body from this page in the create and update requests on the [Managing providers](/agent-auth/bring-your-own-provider/managing-providers) page.
---
# DOCUMENT BOUNDARY
---
# Managing providers
> Use the recommended skill to create, review, update, promote, and delete bring your own provider definitions.
Use this page to create, list, update, promote, and delete custom providers in Scalekit.
Create providers in `Dev` first, validate the definition, and then use the same definition for updates or Production rollout.
Recommended approach
The recommended way to manage providers is with the [`sk-actions-custom-provider` skill](https://github.com/scalekit-inc/skills/tree/main/skills/agent-auth/sk-actions-custom-provider). It keeps payload generation, review, and promotion consistent across Dev and Production.
Use it to:
* Infer the provider auth type
* Generate the provider payload
* Review existing providers before create or update
* Show diffs before updates
* Move provider definitions from Dev to Production
* Prepare the delete curl for a provider
Whenever the skill shows you the final provider payload, review the values carefully before approving or running the next step.
If you prefer to manage custom providers with the APIs directly, use the `curl` commands on this page and the JSON bodies from [Auth patterns](/agent-auth/bring-your-own-provider/auth-types-and-patterns).
Before using the `curl` examples on this page, make sure:
* `SCALEKIT_ENVIRONMENT_URL` points to the Scalekit environment where you want to manage the provider
* `env_access_token` contains a valid environment access token for that environment
## Create a provider
[Section titled “Create a provider”](#create-a-provider)
Create the provider in `Dev` first. Share the provider name, Scalekit credentials, API docs, auth docs, and base API URL if you already know it. The skill will infer the auth pattern, generate the provider payload, and help you create it.
Use one of the JSON payloads from [Auth patterns](/agent-auth/bring-your-own-provider/auth-types-and-patterns) as the request body:
```bash
1
curl --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers" \
2
--header "Authorization: Bearer $env_access_token" \
3
--header "Content-Type: application/json" \
4
--data '{...}'
```
After the provider is created, create a connection in the Scalekit Dashboard and continue with the standard Agent Auth flow.
## List providers
[Section titled “List providers”](#list-providers)
List existing providers before you create or update one. This helps you confirm whether the provider already exists and whether you should create a new provider or update an existing one.
```bash
1
curl --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/providers?filter.provider_type=CUSTOM&page_size=1000" \
2
--header "Authorization: Bearer $env_access_token"
```
## Update a provider
[Section titled “Update a provider”](#update-a-provider)
When a provider changes, use the skill to compare the current provider with the proposed payload. Review auth fields, scopes, and proxy settings carefully before applying the update, because these values affect how future authorization and proxy calls behave.
Use the [List providers](#list-providers) API to get the provider `identifier` from the response before sending the update request.
Use the updated JSON body from [Auth patterns](/agent-auth/bring-your-own-provider/auth-types-and-patterns) and the provider `identifier` in the update request:
```bash
1
curl --location --request PUT "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
2
--header "Authorization: Bearer $env_access_token" \
3
--header "Content-Type: application/json" \
4
--data '{...}'
```
## Move a provider from Dev to Production
[Section titled “Move a provider from Dev to Production”](#move-a-provider-from-dev-to-production)
Use the `Dev` provider as the source of truth. The skill can locate the matching provider in `Dev`, compare it with `Production`, and prepare the correct action from there.
In practice, this means:
* fetch the provider definition from `Dev`
* review the payload
* create it in `Production` if it does not exist
* update it in `Production` if it already exists
Use the same JSON body from [Auth patterns](/agent-auth/bring-your-own-provider/auth-types-and-patterns) for the Production create or update request. This keeps the provider definition consistent between environments.
## Delete a provider
[Section titled “Delete a provider”](#delete-a-provider)
To delete a provider, resolve the correct provider identifier first. If the provider is still in use, remove the related connections or connected accounts before retrying the delete flow.
Use the [List providers](#list-providers) API to get the provider `identifier` from the response before sending the delete request.
```bash
1
curl --location --request DELETE "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
2
--header "Authorization: Bearer $env_access_token"
```
---
# DOCUMENT BOUNDARY
---
# Bring your own provider
> Add custom providers to Agent Auth and extend provider coverage while keeping authentication and authorization in Scalekit.
Bring your own provider lets you add custom providers to Agent Auth when the API you need is not available as a built-in provider.
Use bring your own provider to support unsupported SaaS APIs, partner systems, and internal APIs while keeping authentication, authorization, and secure API access in Scalekit.
Once the provider is created, you use the same Agent Auth flow as other providers: create a connection, create or fetch a connected account, authorize the user, and call the upstream API through Tool Proxy.
Custom providers appear alongside built-in providers when you create a connection in Scalekit:
## Why use bring your own provider
[Section titled “Why use bring your own provider”](#why-use-bring-your-own-provider)
Bring your own provider lets you:
* Extend Agent Auth beyond the built-in provider catalog without inventing a separate auth stack
* Bring unsupported SaaS APIs, partner systems, and internal APIs into the same secure access model
* Reuse connections, connected accounts, and user authorization instead of building one-off auth plumbing
* Keep credential handling, authorization, and governed API access centralized in Scalekit
* Move from provider definition to live upstream API calls through Tool Proxy using the same runtime model as other integrations
Note
Bring your own provider is for proxy-only connectors.
## How bring your own provider works
[Section titled “How bring your own provider works”](#how-bring-your-own-provider-works)
Bring your own provider uses the same Agent Auth model as built-in providers:
1. Create a provider definition
2. Create a connection in Scalekit Dashboard
3. Create a connected account and authorize the user
4. Use Tool Proxy to call the upstream API
Creating the provider defines how Scalekit should authenticate to the upstream API. After that, connections, connected accounts, user authorization, and Tool Proxy work the same way as they do for built-in providers.
---
# DOCUMENT BOUNDARY
---
# Use Tool Proxy
> Use Tool Proxy with your provider after creating a connection, authorizing a user, and setting up a connected account.
Use this page to call a custom provider through Tool Proxy after the provider, connection, and connected account are set up.
The provider definition controls how Scalekit authenticates the upstream API. Your application still uses a connection, a connected account, user authorization, and `actions.request(...)`.
Bring your own provider does not introduce a separate runtime model. You still use the standard Agent Auth flow:
* Create a connection for the provider in Scalekit Dashboard
* Create or fetch the connected account for the user
* Authorize the user if the connected account is not active
* Call the upstream API through Tool Proxy
Tool Proxy uses the connected account context to inject the correct authentication details before routing the request to the upstream API.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Make sure:
* The provider exists and is configured with the right [auth pattern](/agent-auth/bring-your-own-provider/auth-types-and-patterns)
* A [connection](/agent-auth/connections) is configured for the provider
* The [connected account](/agent-auth/connected-accounts) exists
* The user has completed [authorization](/agent-auth/tools/authorize)
Once these pieces are in place, you can call the upstream API through Tool Proxy.
In the request examples below, `path` is relative to the provider `proxy_url`. `connectionName` must match the connection you created, and `identifier` must match the connected account you want to use for the request.
After you create the provider, create a connection for it in the Scalekit Dashboard:
After the user completes authorization, the connected account appears in the Connected Accounts tab and is ready for proxy calls:
## Proxy API calls
[Section titled “Proxy API calls”](#proxy-api-calls)
* Node.js
```typescript
1
import { ScalekitClient } from '@scalekit-sdk/node';
2
import 'dotenv/config';
3
4
const connectionName = 'your-provider-connection'; // get your connection name from connection configurations
5
const identifier = 'user_123'; // your unique user identifier
6
7
// Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
8
const scalekit = new ScalekitClient(
9
process.env.SCALEKIT_ENV_URL,
10
process.env.SCALEKIT_CLIENT_ID,
11
process.env.SCALEKIT_CLIENT_SECRET
12
);
13
const actions = scalekit.actions;
14
15
// Authenticate the user
16
const { link } = await actions.getAuthorizationLink({
17
connectionName,
18
identifier,
19
});
20
console.log('Authorize provider:', link);
21
process.stdout.write('Press Enter after authorizing...');
22
await new Promise(r => process.stdin.once('data', r));
23
24
// Make a request via Scalekit proxy
25
const result = await actions.request({
26
connectionName,
27
identifier,
28
path: '/v1/customers',
29
method: 'GET',
30
});
31
console.log(result);
```
* Python
```python
1
import scalekit.client, os
2
from dotenv import load_dotenv
3
load_dotenv()
4
5
connection_name = "your-provider-connection" # get your connection name from connection configurations
6
identifier = "user_123" # your unique user identifier
7
8
# Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
9
scalekit_client = scalekit.client.ScalekitClient(
10
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
11
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
12
env_url=os.getenv("SCALEKIT_ENV_URL"),
13
)
14
actions = scalekit_client.actions
15
16
# Authenticate the user
17
link_response = actions.get_authorization_link(
18
connection_name=connection_name,
19
identifier=identifier
20
)
21
# present this link to your user for authorization, or click it yourself for testing
22
print("Authorize provider:", link_response.link)
23
input("Press Enter after authorizing...")
24
25
# Make a request via Scalekit proxy
26
result = actions.request(
27
connection_name=connection_name,
28
identifier=identifier,
29
path="/v1/customers",
30
method="GET"
31
)
32
print(result)
```
The request shape stays the same regardless of whether the provider uses OAUTH, BASIC, BEARER, or API\_KEY. The provider definition controls how Scalekit authenticates the upstream call.
---
# DOCUMENT BOUNDARY
---
# Code samples
> Code samples of AI agents using Scalekit along with LangChain, Google ADK, and direct integrations
### [Connect LangChain agents to Gmail](https://github.com/scalekit-inc/sample-langchain-agent)
[Securely connect a LangChain agent to Gmail using Scalekit for authentication. Python example for tool authorization.](https://github.com/scalekit-inc/sample-langchain-agent)
### [Connect Google GenAI agents to Gmail](https://github.com/scalekit-inc/google-adk-agent-example)
[Build a Google ADK agent that securely accesses Gmail tools. Python example demonstrating Scalekit auth integration.](https://github.com/scalekit-inc/google-adk-agent-example)
### [Connect agents to Slack tools](https://github.com/scalekit-inc/python-connect-demos/tree/main/direct)
[Authorize Python agents to use Slack tools with Scalekit. Direct integration example for secure tool access.](https://github.com/scalekit-inc/python-connect-demos/tree/main/direct)
---
# DOCUMENT BOUNDARY
---
# Connected accounts
> Learn how to manage connected accounts in Agent Auth, including user authentication, authorization status, and account lifecycle management.
Connected accounts in Agent Auth represent individual user or organization connections to third-party providers. They contain the authentication state, tokens, and permissions needed to execute tools on behalf of a specific identifier (user\_id, org\_id, or custom identifier).
## What are connected accounts?
[Section titled “What are connected accounts?”](#what-are-connected-accounts)
Connected accounts are the runtime instances that link your users to their third-party application accounts. Each connected account:
* **Links to a connection**: Uses a pre-configured connection for authentication
* **Has a unique identifier**: Associated with a user\_id, org\_id, or custom identifier
* **Maintains auth state**: Tracks whether the user has completed authentication
* **Stores tokens**: Securely holds access tokens and refresh tokens
* **Manages permissions**: Tracks granted scopes and permissions
## Connected account lifecycle
[Section titled “Connected account lifecycle”](#connected-account-lifecycle)
Connected accounts go through several states during their lifecycle:
### Account states
[Section titled “Account states”](#account-states)
1. **Pending**: Account created but user hasn’t completed authentication
2. **Active**: User has authenticated and tokens are valid
3. **Expired**: Tokens have expired and need refresh
4. **Revoked**: User has revoked access to the application
5. **Error**: Account has authentication or configuration errors
6. **Suspended**: Account temporarily disabled
### State transitions
[Section titled “State transitions”](#state-transitions)
## Creating connected accounts
[Section titled “Creating connected accounts”](#creating-connected-accounts)
### Using the dashboard
[Section titled “Using the dashboard”](#using-the-dashboard)
1. **Navigate to connected accounts** in your Agent Auth dashboard
2. **Click create account** to start the process
3. **Select connection** to use for authentication
4. **Enter identifier** (user\_id, email, or custom identifier)
5. **Configure settings** such as scopes and permissions
6. **Generate auth URL** for the user to complete authentication
7. **Monitor status** until user completes the flow
### Using the API
[Section titled “Using the API”](#using-the-api)
Create connected accounts programmatically:
* Python
```python
1
# actions = scalekit_client.actions (initialize ScalekitClient first — see quickstart)
2
response = actions.get_or_create_connected_account(
3
connection_name="gmail",
4
identifier="user_123"
5
)
6
connected_account = response.connected_account
7
print(f"Connected account: {connected_account.id}, status: {connected_account.status}")
```
* Node.js
```typescript
1
// const actions = new ScalekitClient(ENV_URL, CLIENT_ID, CLIENT_SECRET).actions
2
const response = await actions.getOrCreateConnectedAccount({
3
connectionName: 'gmail',
4
identifier: 'user_123',
5
});
6
7
const connectedAccount = response.connectedAccount;
8
console.log('Connected account:', connectedAccount?.id, 'status:', connectedAccount?.status);
```
## Authentication flow
[Section titled “Authentication flow”](#authentication-flow)
### OAuth 2.0 flow
[Section titled “OAuth 2.0 flow”](#oauth-20-flow)
For OAuth connections, connected accounts follow the standard OAuth flow:
1. **Create connected account** with pending status
2. **Generate authorization URL** for the user
3. **User completes OAuth flow** with the third-party provider
4. **Provider redirects back** with authorization code
5. **Exchange code for tokens** and update account status
6. **Account becomes active** and ready for tool execution
### Authorization URL generation
[Section titled “Authorization URL generation”](#authorization-url-generation)
Generate URLs for users to complete authentication:
* Python
```python
1
link_response = actions.get_authorization_link(
2
connection_name="gmail",
3
identifier="user_123"
4
)
5
print(f"Authorization URL: {link_response.link}")
6
# Redirect the user to link_response.link to complete OAuth
```
* Node.js
```typescript
1
const linkResponse = await actions.getAuthorizationLink({
2
connectionName: 'gmail',
3
identifier: 'user_123',
4
});
5
6
console.log('Authorization URL:', linkResponse.link);
7
// Redirect the user to linkResponse.link to complete OAuth
```
### Handling callbacks
[Section titled “Handling callbacks”](#handling-callbacks)
Scalekit handles the OAuth callback automatically. Once the user completes the authorization flow, Scalekit exchanges the code for tokens and updates the connected account status to `ACTIVE`.
## Managing connected accounts
[Section titled “Managing connected accounts”](#managing-connected-accounts)
### Account information
[Section titled “Account information”](#account-information)
Retrieve connected account details and OAuth tokens:
* Python
```python
1
response = actions.get_connected_account(
2
connection_name="gmail",
3
identifier="user_123"
4
)
5
connected_account = response.connected_account
6
7
# Extract OAuth tokens from authorization details
8
tokens = connected_account.authorization_details["oauth_token"]
9
access_token = tokens["access_token"]
10
refresh_token = tokens["refresh_token"]
11
12
print(f"Account ID: {connected_account.id}")
13
print(f"Status: {connected_account.status}")
```
* Node.js
```typescript
1
const accountResponse = await actions.getConnectedAccount({
2
connectionName: 'gmail',
3
identifier: 'user_123',
4
});
5
6
const connectedAccount = accountResponse?.connectedAccount;
7
const authDetails = connectedAccount?.authorizationDetails;
8
9
// Extract OAuth tokens from authorization details
10
const accessToken = (authDetails && authDetails.details?.case === 'oauthToken')
11
? authDetails.details.value?.accessToken
12
: undefined;
13
const refreshToken = (authDetails && authDetails.details?.case === 'oauthToken')
14
? authDetails.details.value?.refreshToken
15
: undefined;
16
17
console.log('Account ID:', connectedAccount?.id);
18
console.log('Status:', connectedAccount?.status);
```
### Token management
[Section titled “Token management”](#token-management)
Connected accounts automatically handle token lifecycle:
**Automatic token refresh:**
* Tokens are refreshed automatically before expiration
* Refresh happens transparently during tool execution
* Failed refresh attempts update account status to expired
**Manual token refresh:**
There is no SDK method to manually trigger a token refresh. If a connected account’s status is `EXPIRED` or `ERROR`, generate a new authorization link and prompt the user to re-authorize:
* Python
```python
1
response = actions.get_or_create_connected_account(
2
connection_name="gmail",
3
identifier="user_123"
4
)
5
connected_account = response.connected_account
6
7
if connected_account.status != "ACTIVE":
8
# Re-authorize the user to refresh their tokens
9
link_response = actions.get_authorization_link(
10
connection_name="gmail",
11
identifier="user_123"
12
)
13
print(f"Re-authorization required. Send user to: {link_response.link}")
```
* Node.js
```typescript
1
const response = await actions.getOrCreateConnectedAccount({
2
connectionName: 'gmail',
3
identifier: 'user_123',
4
});
5
6
const connectedAccount = response.connectedAccount;
7
8
if (connectedAccount?.status !== 'ACTIVE') {
9
// Re-authorize the user to refresh their tokens
10
const linkResponse = await actions.getAuthorizationLink({
11
connectionName: 'gmail',
12
identifier: 'user_123',
13
});
14
console.log('Re-authorization required. Send user to:', linkResponse.link);
15
}
```
### Account status monitoring
[Section titled “Account status monitoring”](#account-status-monitoring)
Monitor account authentication status:
* Python
```python
1
response = actions.get_connected_account(
2
connection_name="gmail",
3
identifier="user_123"
4
)
5
connected_account = response.connected_account
6
7
# Possible status values:
8
# - PENDING: Waiting for user authentication
9
# - ACTIVE: Authenticated and ready
10
# - EXPIRED: Tokens expired, needs re-authorization
11
# - REVOKED: User revoked access
12
# - ERROR: Authentication error
13
print(f"Account status: {connected_account.status}")
```
* Node.js
```typescript
1
const accountResponse = await actions.getConnectedAccount({
2
connectionName: 'gmail',
3
identifier: 'user_123',
4
});
5
6
const connectedAccount = accountResponse?.connectedAccount;
7
8
// Possible status values:
9
// - PENDING: Waiting for user authentication
10
// - ACTIVE: Authenticated and ready
11
// - EXPIRED: Tokens expired, needs re-authorization
12
// - REVOKED: User revoked access
13
// - ERROR: Authentication error
14
console.log('Account status:', connectedAccount?.status);
```
## Account permissions and scopes
[Section titled “Account permissions and scopes”](#account-permissions-and-scopes)
Scopes define what actions a connected account can perform on a user’s behalf. Understanding how scopes are configured and updated is critical to building reliable agent integrations.
### Scopes are set at the connection level
[Section titled “Scopes are set at the connection level”](#scopes-are-set-at-the-connection-level)
Scopes are configured at the **connection level**, not at the individual connected account level. When a user completes the OAuth authorization flow for a connected account, they approve exactly the scopes defined on that connection.
**Scopes are read-only after a connected account is created.** There is no API or SDK method to modify the granted scopes on an existing connected account after the user has completed authentication.
### Add or change scopes
[Section titled “Add or change scopes”](#add-or-change-scopes)
To request additional scopes for an existing connected account:
1. **Update the connection configuration** — In the Scalekit dashboard, navigate to the connection and add the new scopes.
2. **Generate a new magic link** — Use the Scalekit dashboard or API to create a new authorization link for the user.
3. **User approves the updated consent screen** — The user visits the link and approves the expanded OAuth consent screen with the new scopes.
4. **Connected account is updated** — After the user approves, Scalekit updates the connected account with the new token set.
The user must go through the OAuth flow again whenever scopes change. There is no way to silently add scopes on their behalf.
### Account and connector status values
[Section titled “Account and connector status values”](#account-and-connector-status-values)
When working with connected accounts, you may encounter the following enum values from the Scalekit platform:
**Connector status**
| Value | Description |
| --------------------------- | ----------------------------------------------------- |
| `CONNECTOR_STATUS_ACTIVE` | Connector is configured and operational |
| `CONNECTOR_STATUS_INACTIVE` | Connector is configured but not active |
| `CONNECTOR_STATUS_PENDING` | Connector setup is incomplete |
| `CONNECTOR_STATUS_ERROR` | Connector has a configuration or authentication error |
**Connector type**
| Value | Description |
| --------------------------- | ------------------------------------------------- |
| `CONNECTOR_TYPE_OAUTH2` | OAuth 2.0 connection (e.g., Gmail, Slack, GitHub) |
| `CONNECTOR_TYPE_API_KEY` | API key-based connection (e.g., Zendesk, HubSpot) |
| `CONNECTOR_TYPE_BASIC_AUTH` | Username and password connection |
These values are returned in API responses when listing or inspecting connections and connected accounts.
## Account metadata and settings
[Section titled “Account metadata and settings”](#account-metadata-and-settings)
### Custom metadata
[Section titled “Custom metadata”](#custom-metadata)
Custom metadata is managed via the Scalekit dashboard.
## Bulk operations
[Section titled “Bulk operations”](#bulk-operations)
### Managing multiple accounts
[Section titled “Managing multiple accounts”](#managing-multiple-accounts)
The Python SDK supports read-only retrieval via `actions.get_connected_account` (Python) / `actions.getConnectedAccount` (Node.js). Use `actions.get_or_create_connected_account` when you need create-or-retrieve semantics. Bulk list and delete operations (`actions.listConnectedAccounts`, `actions.deleteConnectedAccount`) are available in the Node.js SDK, or via the direct API and dashboard.
* Python
```python
1
# Get or create a connected account by identifier
2
response = actions.get_or_create_connected_account(
3
connection_name="gmail",
4
identifier="user_123"
5
)
6
connected_account = response.connected_account
7
print(f"Account: {connected_account.id}, Status: {connected_account.status}")
```
* Node.js
```typescript
1
// List connected accounts
2
const listResponse = await actions.listConnectedAccounts({
3
connectionName: 'gmail',
4
});
5
console.log('Connected accounts:', listResponse);
6
7
// Delete a connected account
8
await actions.deleteConnectedAccount({
9
connectionName: 'gmail',
10
identifier: 'user_123',
11
});
12
console.log('Connected account deleted');
```
## Error handling
[Section titled “Error handling”](#error-handling)
### Common errors
[Section titled “Common errors”](#common-errors)
Handle common connected account errors:
* Python
```python
1
try:
2
response = actions.get_connected_account(
3
connection_name="gmail",
4
identifier="user_123"
5
)
6
connected_account = response.connected_account
7
except Exception as e:
8
print(f"Error retrieving connected account: {e}")
9
# Check connected_account.status for EXPIRED, REVOKED, or ERROR states
10
# and prompt the user to re-authorize if needed
```
* Node.js
```typescript
1
try {
2
const accountResponse = await actions.getConnectedAccount({
3
connectionName: 'gmail',
4
identifier: 'user_123',
5
});
6
const connectedAccount = accountResponse?.connectedAccount;
7
console.log('Account status:', connectedAccount?.status);
8
} catch (error) {
9
console.error('Error retrieving connected account:', error);
10
// Check connectedAccount?.status for EXPIRED, REVOKED, or ERROR states
11
// and prompt the user to re-authorize if needed
12
}
```
### Error recovery
[Section titled “Error recovery”](#error-recovery)
Implement error recovery strategies:
1. **Detect error** - Monitor account status and API responses
2. **Classify error** - Determine if error is recoverable
3. **Attempt recovery** - Try token refresh or re-authentication
4. **Notify user** - Inform user if manual action is required
5. **Update status** - Update account status based on recovery result
## Security considerations
[Section titled “Security considerations”](#security-considerations)
### Token security
[Section titled “Token security”](#token-security)
Protect user tokens and credentials:
* **Encryption**: All tokens are encrypted at rest and in transit
* **Token rotation**: Implement regular token rotation
* **Access logging**: Log all token access and usage
* **Secure storage**: Use secure storage mechanisms for tokens
### Permission management
[Section titled “Permission management”](#permission-management)
Follow principle of least privilege:
* **Minimal scopes**: Request only necessary permissions
* **Scope validation**: Verify permissions before tool execution
* **Regular audit**: Review granted permissions regularly
* **User consent**: Ensure users understand granted permissions
### Account isolation
[Section titled “Account isolation”](#account-isolation)
Ensure proper account isolation:
* **Tenant isolation**: Separate accounts by tenant/organization
* **User isolation**: Prevent cross-user data access
* **Connection isolation**: Separate different connection types
* **Audit trail**: Maintain detailed audit logs
## Monitoring and analytics
[Section titled “Monitoring and analytics”](#monitoring-and-analytics)
### Account health monitoring
[Section titled “Account health monitoring”](#account-health-monitoring)
Monitor the status of connected accounts by calling `actions.get_connected_account` (Python) or `actions.getConnectedAccount` (Node.js) and inspecting the `status` field. Accounts in a non-`ACTIVE` state may require re-authorization.
### Usage analytics
[Section titled “Usage analytics”](#usage-analytics)
Track usage patterns and tool execution results through the Scalekit dashboard. SDK methods for usage analytics are not currently available.
## Best practices
[Section titled “Best practices”](#best-practices)
### Account lifecycle management
[Section titled “Account lifecycle management”](#account-lifecycle-management)
* **Regular cleanup**: Remove unused or expired accounts
* **Status monitoring**: Monitor account status changes
* **Proactive refresh**: Refresh tokens before expiration
* **User notifications**: Notify users of authentication issues
### Performance optimization
[Section titled “Performance optimization”](#performance-optimization)
* **Connection pooling**: Reuse connections efficiently
* **Token caching**: Cache tokens appropriately
* **Batch operations**: Use bulk operations when possible
* **Async processing**: Handle authentication flows asynchronously
### User experience
[Section titled “User experience”](#user-experience)
* **Clear error messages**: Provide helpful error messages to users
* **Seamless re-auth**: Make re-authentication flows smooth
* **Status visibility**: Show users their connection status
* **Easy revocation**: Allow users to easily revoke access
## Testing connected accounts
[Section titled “Testing connected accounts”](#testing-connected-accounts)
### Development testing
[Section titled “Development testing”](#development-testing)
Test connected accounts in development:
* Python
```python
1
# Create or retrieve a test connected account
2
response = actions.get_or_create_connected_account(
3
connection_name="gmail",
4
identifier="test_user"
5
)
6
test_account = response.connected_account
7
print(f"Test account: {test_account.id}, status: {test_account.status}")
```
* Node.js
```typescript
1
// Create or retrieve a test connected account
2
const response = await actions.getOrCreateConnectedAccount({
3
connectionName: 'gmail',
4
identifier: 'test_user',
5
});
6
7
const testAccount = response.connectedAccount;
8
console.log('Test account:', testAccount?.id, 'status:', testAccount?.status);
```
### Integration testing
[Section titled “Integration testing”](#integration-testing)
Test authentication flows:
1. **Create test connection** with test credentials
2. **Create connected account** with test identifier
3. **Generate auth URL** and complete OAuth flow
4. **Verify account status** becomes active
5. **Test tool execution** with the account
6. **Test token refresh** and error scenarios
Next, learn how to [authorize a user](/agent-auth/tools/authorize) so connected accounts can complete authentication before tool execution.
---
# DOCUMENT BOUNDARY
---
# Connections
> Learn how to configure and manage connections in Agent Auth to enable authentication and tool execution with third-party providers.
A **connection** is a configured integration between Scalekit and a third-party provider. It holds the credentials and settings Scalekit needs to interact with that provider’s API on behalf of your users — OAuth client secrets, API keys, scopes, and so on.
You create one connection per provider in the Scalekit Dashboard. Once active, it can be shared across all your users.
## Connection types
[Section titled “Connection types”](#connection-types)
| Type | When to use |
| ---------------- | --------------------------------------------------------------------------------- |
| **OAuth 2.0** | Providers like Notion, Gmail, Slack, GitHub that use user-delegated authorization |
| **API Key** | Providers like Exa, HarvestAPI, Snowflake that authenticate with a static key |
| **Bearer token** | Providers that accept a long-lived bearer token |
| **Basic auth** | Providers that use username + password authentication |
## Creating a connection
[Section titled “Creating a connection”](#creating-a-connection)
1. Open the **Connections** section in the [Scalekit Dashboard](https://app.scalekit.com)
2. Click **Add connection** and select a provider
3. Enter the required credentials (OAuth client ID/secret, API key, etc.)
4. Save — the connection is now available for use
For a step-by-step example, see how to set up a [Gmail connection](/reference/agent-connectors/gmail/).
Next, learn how to create and manage [Connected accounts](/agent-auth/connected-accounts) that use these connections to authenticate and execute tools for your users.
---
# DOCUMENT BOUNDARY
---
# Agno
> Learn how to use CrewAI with Agent Auth.
# Agno
[Section titled “Agno”](#agno)
Agno is a framework for building AI agents. It provides a set of tools and abstractions for building AI agents.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# Anthropic
> Learn how to enable tool calling with Agent Auth on top of Anthropic's models.
# Anthropic
[Section titled “Anthropic”](#anthropic)
Anthropic is a framework for building AI agents. It provides a set of tools and abstractions for building AI agents.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# Google ADK
> Build a Google ADK agent that authenticates users with Gmail and executes tools on their behalf using Scalekit Agent Auth.
Build a Gmail-powered AI agent using Google ADK that authenticates users via OAuth 2.0 and fetches their last 5 unread emails using Scalekit Agent Auth. Visit the [Google ADK quickstart guide](https://google.github.io/adk-docs/get-started/quickstart/) to set up Google ADK before starting.
[Full code on GitHub ](https://github.com/scalekit-inc/google-adk-agent-example)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before you start, ensure you have:
* **Scalekit account and API credentials** — Get your Client ID and Client Secret from the [Scalekit dashboard](https://app.scalekit.com)
* **Google API Key** — Obtain from [Google AI Studio](https://aistudio.google.com)
* **Gmail account** — For testing the OAuth authentication flow
1. ### Set up your environment
[Section titled “Set up your environment”](#set-up-your-environment)
Install the Scalekit Python SDK and Google ADK, then initialize the client. Get your credentials from **Developers → Settings → API Credentials** in the [dashboard](https://app.scalekit.com).
```sh
pip install scalekit-sdk-python google-adk
```
```python
import scalekit.client
import os
scalekit_client = scalekit.client.ScalekitClient(
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit_client.actions
```
2. ### Create a connected account
[Section titled “Create a connected account”](#create-a-connected-account)
Authorize a user to access their Gmail account by creating a connected account. This represents the user’s connection to their Gmail account:
```python
1
# Create a connected account for user if it doesn't exist already
2
response = actions.get_or_create_connected_account(
3
connection_name="GMAIL",
4
identifier="user_123"
5
)
6
connected_account = response.connected_account
7
8
print(f'Connected account created: {connected_account.id}')
```
3. ### Authenticate the user
[Section titled “Authenticate the user”](#authenticate-the-user)
For Scalekit to execute tools on behalf of the user, the user must grant authorization to access their Gmail account. Scalekit automatically handles the entire OAuth workflow, including token refresh.
```python
1
# Check if the user needs to authorize their Gmail connection
2
# This handles both new users and cases where the access token has expired
3
if connected_account.status != "ACTIVE":
4
# Generate an authorization link for the user to complete OAuth flow
5
link_response = actions.get_authorization_link(
6
connection_name="GMAIL",
7
identifier="user_123"
8
)
9
10
# Display the authorization link to the user
11
print(f"🔗 Authorize Gmail access: {link_response.link}")
12
input("⎆ Press Enter after completing authorization...")
13
14
# In production, redirect users to the authorization URL instead of using input()
15
# The user will be redirected back to your app after successful authorization
```
4. ### Build a Google ADK agent
[Section titled “Build a Google ADK agent”](#build-a-google-adk-agent)
Build a simple agent that fetches the last 5 unread emails from the user’s inbox and generates a summary.
```python
1
from google.adk.agents import Agent
2
3
# Get Gmail tools from Scalekit in Google ADK format
4
gmail_tools = actions.google.get_tools(
5
providers=["GMAIL"],
6
identifier="user_123",
7
page_size=100
8
)
9
10
# Create a Google ADK agent with Gmail tools
11
gmail_agent = Agent(
12
name="gmail_assistant",
13
model="gemini-2.5-flash",
14
description="Gmail assistant that can read and manage emails",
15
instruction=(
16
"You are a helpful Gmail assistant. You can read, send, and organize emails. "
17
"When asked to fetch emails, focus on unread messages and provide clear summaries. "
18
"Always be helpful and professional."
19
),
20
tools=gmail_tools
21
)
22
23
# Use the agent to fetch and summarize unread emails
24
response = gmail_agent.process_request(
25
"fetch my last 5 unread emails and summarize them"
26
)
27
print(response)
```
---
# DOCUMENT BOUNDARY
---
# Google GenAI
> Learn how to use Google GenAI with Agent Auth.
# Google GenAI
[Section titled “Google GenAI”](#google-genai)
Google GenAI is a framework for building AI agents. It provides a set of tools and abstractions for building AI agents.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# LangChain
> Build a LangChain agent that authenticates users with Gmail and executes tools on their behalf using Scalekit Agent Auth.
This guide shows how to build a LangChain agent that authenticates users with Gmail via OAuth 2.0 and fetches their last 5 unread emails using Scalekit Agent Auth.
[Full code on GitHub ](https://github.com/scalekit-inc/sample-langchain-agent)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before you start, make sure you have:
* **Scalekit API credentials** — Client ID and Client Secret from [app.scalekit.com](https://app.scalekit.com)
* **OpenAI API Key** — Get from [OpenAI Platform](https://platform.openai.com/api-keys)
1. ### Set up your environment
[Section titled “Set up your environment”](#set-up-your-environment)
Install the Scalekit Python SDK and initialize the client. Get your credentials from **Developers → Settings → API Credentials** in the [dashboard](https://app.scalekit.com).
```sh
pip install scalekit-sdk-python langchain langchain-openai
```
```python
import scalekit.client
import os
from dotenv import load_dotenv
load_dotenv()
scalekit_client = scalekit.client.ScalekitClient(
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit_client.actions
```
2. ### Create a connected account
[Section titled “Create a connected account”](#create-a-connected-account)
Authorize a user to access their Gmail account by creating a connected account. This represents the user’s connection to their Gmail account:
```python
1
# Create a connected account for user if it doesn't exist already
2
response = actions.get_or_create_connected_account(
3
connection_name="gmail",
4
identifier="user_123" # unique identifier; replace with your system's user ID
5
)
6
connected_account = response.connected_account
7
8
print(f'Connected account created: {connected_account.id}')
```
3. ### Authenticate the user
[Section titled “Authenticate the user”](#authenticate-the-user)
For Scalekit to execute tools on behalf of the user, the user must grant authorization to access their Gmail account. Scalekit automatically handles the entire OAuth workflow, including token refresh.
```python
1
# If the user hasn't yet authorized the gmail connection or if the user's access token is expired,
2
# generate a magic link and redirect the user to this link so that the user can complete authorization
3
if(connected_account.status != "ACTIVE"):
4
link_response = actions.get_authorization_link(
5
connection_name="gmail",
6
identifier="user_123"
7
)
8
print(f"🔗click on the link to authorize gmail", link_response.link)
9
input(f"⎆ Press Enter after authorizing gmail...")
10
11
# In a real app, redirect the user to this URL so that the user can complete the authentication process for their gmail account
```
4. ### Build a LangChain agent
[Section titled “Build a LangChain agent”](#build-a-langchain-agent)
Build a simple agent that fetches the last 5 unread emails from the user’s inbox and generates a summary.
```python
1
from langchain_openai import ChatOpenAI
2
from langchain.agents import AgentExecutor, create_openai_tools_agent
3
from langchain_core.prompts import SystemMessagePromptTemplate, MessagesPlaceholder, HumanMessagePromptTemplate,PromptTemplate, ChatPromptTemplate
4
5
# use scalekit SDK to fetch all GMAIL tools in langchain format
6
tools = actions.langchain.get_tools(
7
identifier="user_123",
8
providers = ["GMAIL"], # all tools for provider used by default
9
page_size=100
10
)
11
12
prompt = ChatPromptTemplate.from_messages([
13
SystemMessagePromptTemplate(prompt=PromptTemplate(input_variables=[], template="You are a helpful assistant. Use tools if needed")),
14
MessagesPlaceholder(variable_name="chat_history", optional=True),
15
HumanMessagePromptTemplate(prompt=PromptTemplate(input_variables=["input"], template="{input}")),
16
MessagesPlaceholder(variable_name="agent_scratchpad")
17
])
18
19
llm = ChatOpenAI(model="gpt-4o")
20
agent = create_openai_tools_agent(llm, tools, prompt)
21
agent_executor = AgentExecutor(agent=agent, tools=tools,verbose=True)
22
result = agent_executor.invoke({"input":"fetch my last 5 unread emails and summarize it"}
23
)
```
---
# DOCUMENT BOUNDARY
---
# Mastra
> Learn how to use Mastra with Agent Auth.
# Mastra
[Section titled “Mastra”](#mastra)
Mastra is a framework for building AI agents. It provides a set of tools and abstractions for building AI agents.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# MCP
> Learn how to use MCP with Agent Auth.
# MCP
[Section titled “MCP”](#mcp)
MCP is a framework for building AI agents. It provides a set of tools and abstractions for building AI agents.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# OpenAI
> Learn how to use OpenAI with Agent Auth.
# OpenAI
[Section titled “OpenAI”](#openai)
OpenAI is a framework for building AI agents. It provides a set of tools and abstractions for building AI agents.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# Vercel
> Learn how to use Vercel with Agent Auth.
# Vercel
[Section titled “Vercel”](#vercel)
Vercel is a framework for building AI agents. It provides a set of tools and abstractions for building AI agents.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# Give your agent tool access via MCP
> Create a per-user MCP server with whitelisted, pre-authenticated tools — then hand your agent a single URL.
When your agent needs to act on behalf of a user — reading their email, creating calendar events — each user must authenticate to each service separately. Managing those credentials in your agent adds complexity and security risk.
Scalekit solves this with per-user MCP servers. You define which tools and connections a server exposes, and Scalekit gives you a unique, pre-authenticated URL for each user. Hand that URL to your agent — it calls tools through MCP, Scalekit handles the auth. MCP servers only support Streamable HTTP transport.
Testing only — not for production
This feature is in beta and intended for testing purposes only. Do not use it in production environments.
## How it works
[Section titled “How it works”](#how-it-works)
Two objects are central to this model:
| Object | What it is | Created |
| ---------------- | ------------------------------------------------------------------------ | ----------------- |
| **MCP config** | A reusable template that defines which connections and tools are exposed | Once, by your app |
| **MCP instance** | A per-user instantiation of a config, with its own URL | Once per user |
Your app creates a config once, then calls `ensure_instance` whenever a new user needs access. Scalekit generates a unique URL for that user. When the agent calls tools through that URL, Scalekit routes each call using the user’s pre-authorized credentials.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before you start, make sure you have:
* **Scalekit API credentials** — Go to **Dashboard → Settings** and copy your `environment_url`, `client_id` and `client_secret`
* **Gmail and Google Calendar connections configured in Scalekit:**
* **Gmail**: **Dashboard → Connections** (Agent Auth) → Create Connection → Gmail → set `Connection Name = MY_GMAIL` → Save
* **Google Calendar**: **Dashboard → Connections** (Agent Auth) → Create Connection → Google Calendar → set `Connection Name = MY_CALENDAR` → Save
1. ## Install the SDK and initialize the client
[Section titled “Install the SDK and initialize the client”](#install-the-sdk-and-initialize-the-client)
Install the Scalekit Python SDK:
```sh
pip install scalekit-sdk-python python-dotenv>=1.0.1
```
Initialize the client using your environment credentials:
```python
import os
import scalekit.client
from scalekit.actions.models.mcp_config import McpConfigConnectionToolMapping
scalekit_client = scalekit.client.ScalekitClient(
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
env_url=os.getenv("SCALEKIT_ENV_URL"),
)
my_mcp = scalekit_client.actions.mcp
```
2. ## Create an MCP config
[Section titled “Create an MCP config”](#create-an-mcp-config)
An MCP config is a reusable template. It declares which connections and tools your server exposes. Create it once — not once per user.
```python
cfg_response = my_mcp.create_config(
name="reminder-manager",
description="Summarizes latest email and creates a reminder event",
connection_tool_mappings=[
McpConfigConnectionToolMapping(
connection_name="MY_GMAIL",
tools=["gmail_fetch_mails"],
),
McpConfigConnectionToolMapping(
connection_name="MY_CALENDAR",
tools=["googlecalendar_create_event"],
),
],
)
config_name = cfg_response.config.name
```
3. ## Get a per-user MCP URL
[Section titled “Get a per-user MCP URL”](#get-a-per-user-mcp-url)
Call `ensure_instance` to get a unique MCP URL for a specific user. If an instance already exists for that user, Scalekit returns it — so it’s safe to call on every login.
```python
inst_response = my_mcp.ensure_instance(
config_name=config_name,
user_identifier="john-doe",
)
mcp_url = inst_response.instance.url
print("MCP URL:", mcp_url)
```
Before the agent can use this URL, the user must authorize each connection. Retrieve the auth links and surface them to the user:
```python
auth_state_response = my_mcp.get_instance_auth_state(
instance_id=inst_response.instance.id,
include_auth_links=True,
)
for conn in getattr(auth_state_response, "connections", []):
print("Connection:", conn.connection_name,
"| Status:", conn.connected_account_status,
"| Auth link:", conn.authentication_link)
```
Complete authentication
Open the printed links in your browser and complete authentication for each connection.
In production, surface these links to users via your app UI, email, or a Slack message. Poll `get_instance_auth_state` (without `include_auth_links`) to check when a user has completed authorization before passing the URL to your agent.
At this point you have a per-user MCP URL. You can pass it to any spec-compliant MCP client — MCP Inspector, Claude Desktop, or an agent framework. The next step shows an example using LangChain.
4. ## Connect an agent (LangChain example)
[Section titled “Connect an agent (LangChain example)”](#connect-an-agent-langchain-example)
Install the LangChain dependencies:
```sh
pip install langgraph>=0.6.5 langchain-mcp-adapters>=0.1.9 openai>=1.53.0
```
Set your OpenAI API key:
```sh
export OPENAI_API_KEY=your-openai-api-key
```
Pass the MCP URL to a LangChain agent. The agent discovers available tools automatically — no additional auth configuration required:
```python
import asyncio
from langgraph.prebuilt import create_react_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
async def run_agent(mcp_url: str):
client = MultiServerMCPClient(
{
"reminder_demo": {
"transport": "streamable_http",
"url": mcp_url,
},
}
)
tools = await client.get_tools()
agent = create_react_agent("openai:gpt-4.1", tools)
response = await agent.ainvoke({
"messages": "Get my latest email and create a calendar reminder in the next 15 minutes."
})
print(response)
asyncio.run(run_agent(mcp_url))
```
MCP client compatibility
This MCP server works with MCP Inspector, Claude Desktop, and any spec-compliant MCP client. ChatGPT’s beta connector may not work correctly — it is still in beta and does not fully implement the MCP specification.
Full working code for all steps above is on [GitHub](https://github.com/scalekit-inc/python-connect-demos/tree/main/mcp).
## Next steps
[Section titled “Next steps”](#next-steps)
[LangChain integration ](/agent-auth/frameworks/langchain)Use LangChain to build agents that connect to Scalekit MCP servers.
[Google ADK integration ](/agent-auth/frameworks/google-adk)Connect Scalekit tools to agents built with Google's Agent Development Kit.
[Manage connections ](/agent-auth/connections)Learn how to configure and manage provider connections in Scalekit.
---
# DOCUMENT BOUNDARY
---
# OpenClaw skill
> Connect OpenClaw agents to third-party services through Scalekit. Supports LinkedIn, Notion, Slack, Gmail, and 50+ providers.
Use the Scalekit Agent Auth skill for [OpenClaw](https://github.com/scalekit-inc/openclaw-skill) to let your AI agents execute actions on third-party services directly from conversations. Search LinkedIn, read Notion pages, send Slack messages, query Snowflake, and more — all through Scalekit Connect without storing tokens or API keys in your agent.
Security considerations for AI agents
Scalekit stores tokens and API keys securely with full audit logging. OpenClaw, like all AI agent frameworks, is vulnerable to prompt injection and other agent-level attacks. Follow security best practices to protect your instance.
When you ask Claude to interact with a third-party service, the skill:
* Finds the configured provider in Scalekit (e.g., [Gmail connection setup](/reference/agent-connectors/gmail/)) and identifies which connection to use based on the requested action
* Checks if the connection is active. For OAuth connections, it generates a magic link for new authorizations. For API key connections, it provides Dashboard guidance for setup
* Retrieves available tools and their parameter schemas for the provider, determining what actions are possible
* Calls the right tool with the correct parameters and returns the result to your conversation
* If no tool exists for the action, routes the request through Scalekit’s HTTP proxy, making direct API calls on your behalf
Automatic auth flow detection
The skill automatically detects whether a connection uses OAuth or an API key and applies the correct auth flow — no configuration needed.
Your agent never stores tokens or API keys. Scalekit acts as a token vault, managing all OAuth tokens, API keys, and credentials. The skill retrieves only what it needs at runtime, scoped to the requesting user.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* [OpenClaw](https://openclaw.ai) installed and configured
* A Scalekit account with Agent Auth enabled — [sign up at app.scalekit.com](https://app.scalekit.com)
* `python3` and `uv` available in your PATH
## Get started
[Section titled “Get started”](#get-started)
1. ## Install the skill
[Section titled “Install the skill”](#install-the-skill)
Install the skill from ClawHub:
```bash
clawhub install scalekit-agent-auth
```
2. ## Configure credentials
[Section titled “Configure credentials”](#configure-credentials)
Add your Scalekit credentials to `.env` in your project root:
.env
```bash
1
TOOL_CLIENT_ID=skc_your_client_id # Your Scalekit client ID
2
TOOL_CLIENT_SECRET=your_client_secret # Your Scalekit client secret
3
TOOL_ENV_URL=https://your-env.scalekit.cloud # Your Scalekit environment URL
4
TOOL_IDENTIFIER=your_default_user_identifier # Default user context for tool calls
```
| Parameter | Description |
| -------------------- | --------------------------------------------------- |
| `TOOL_CLIENT_ID` | Your Scalekit client ID Required |
| `TOOL_CLIENT_SECRET` | Your Scalekit client secret Required |
| `TOOL_ENV_URL` | Your Scalekit environment URL Required |
| `TOOL_IDENTIFIER` | Default user context for all tool calls Recommended |
Environment variable security
Never commit `.env` files to version control. Add `.env` to your `.gitignore` file to prevent accidental exposure of credentials.
3. ## Usage
[Section titled “Usage”](#usage)
* Gmail
```txt
You: Show me my latest unread emails
```
OpenClaw will automatically:
1. Look up the `GMAIL` connection
2. Verify it’s active (or generate a magic link to authorize if needed)
3. Fetch the `gmail_list_emails` tool schema
4. Return your latest unread emails
* Notion
```txt
You: Read my Notion page https://notion.so/My-Page-abc123
```
OpenClaw will:
1. Look up the `NOTION` connection
2. If not yet authorized, generate a magic link for you to complete OAuth
3. Fetch the `notion_page_get` tool schema
4. Return the page content
## Supported providers
[Section titled “Supported providers”](#supported-providers)
Any provider configured in Scalekit works with the OpenClaw skill — including Notion, Slack, Gmail, Google Sheets, GitHub, Salesforce, HubSpot, Linear, Snowflake, Exa, HarvestAPI, and 50+ more.
[Browse connections ](/guides/integrations/agent-connectors)See all supported providers in the Scalekit dashboard
[ClawHub listing ](https://clawhub.dev/skills/scalekit-agent-auth)Install scalekit-agent-auth from ClawHub
## Common scenarios
[Section titled “Common scenarios”](#common-scenarios)
How do I authorize a new connection?
When you request an action for a connection that isn’t yet authorized, the skill automatically generates a magic link. Click the link to complete OAuth authorization in your browser. After authorization, return to your OpenClaw conversation and retry the action.
For API key-based connections (like Snowflake), you’ll need to configure credentials directly in the Scalekit Dashboard under **Connections**.
How do I switch between different user contexts?
Set `TOOL_IDENTIFIER` in your `.env` file to define a default user context. All tool calls will execute with that user’s permissions and connected accounts.
To use a different user context for a specific conversation, you can override the identifier by setting it in your OpenClaw configuration or passing it as a parameter when invoking the skill.
Why am I seeing a “connection not found” error?
This error occurs when the skill cannot find a configured connection for the requested provider. Check the following:
1. **Verify the connection exists** — Go to **Dashboard > Connections** and confirm the provider is configured
2. **Check connection status** — Ensure the connection shows as “Active” in the dashboard
3. **Verify environment** — Confirm you’re using the correct `TOOL_ENV_URL` for your environment
How do I debug tool execution issues?
Enable debug logging in your OpenClaw configuration to see detailed information about tool calls:
```bash
TOOL_DEBUG=true
```
This logs the tool name, parameters, and response for each execution, helping you identify issues with parameter formatting or API responses.
---
# DOCUMENT BOUNDARY
---
# Overview
> Learn about Agent Auth, Scalekit's authentication solution for securely connecting to third-party applications through OAuth 2.0
Agent Auth is Scalekit’s authentication solution that enables your applications to securely connect to third-party services on behalf of your users. It handles the complexity of OAuth flows, token management, and multi-provider authentication for popular business applications like Gmail, Slack, Jira, and more.
## What is Agent Auth?
[Section titled “What is Agent Auth?”](#what-is-agent-auth)
Agent Auth simplifies third-party authentication by providing:
* **Multi-provider OAuth**: Support for OAuth 2.0 flows across all major providers
* **Unified authentication API**: Single interface for managing connections to any provider
* **Automatic token management**: Token refresh, storage, and lifecycle handling
* **Flexible authentication modes**: Use Scalekit-managed OAuth or bring your own credentials
* **Secure token handling**: Encrypted token storage and transmission
## Key concepts
[Section titled “Key concepts”](#key-concepts)
### Providers
[Section titled “Providers”](#providers)
Providers are third-party applications that your users can authenticate with. Agent Auth supports OAuth 2.0 flows for popular platforms including Gmail, Slack, GitHub, Jira, and many more.
### Connections
[Section titled “Connections”](#connections)
Connections define the authentication configuration for a specific provider. Each connection contains:
* **Authentication credentials** (OAuth client ID/secret, API keys)
* **OAuth configuration** (authorization URLs, token endpoints, scopes)
* **Provider-specific settings** (rate limits, API versions)
### Connected accounts
[Section titled “Connected accounts”](#connected-accounts)
Connected accounts represent the authenticated link between a user in your application and their account on a third-party provider. Each connected account maintains:
* **Authentication state** (active, expired, revoked)
* **Access tokens** and refresh tokens with automatic refresh handling
* **Granted OAuth scopes** and permissions
* **Token expiration** tracking and lifecycle management
## Architecture overview
[Section titled “Architecture overview”](#architecture-overview)
## How authentication works
[Section titled “How authentication works”](#how-authentication-works)
### 1. Configure provider connections
[Section titled “1. Configure provider connections”](#1-configure-provider-connections)
Set up OAuth credentials for each provider you want to support:
```javascript
1
// Create a connection for Gmail with OAuth 2.0
2
const gmailConnection = await agentConnect.connections.create({
3
provider: 'gmail',
4
auth_type: 'oauth2',
5
credentials: {
6
client_id: 'your-gmail-client-id',
7
client_secret: 'your-gmail-client-secret'
8
},
9
scopes: ['https://www.googleapis.com/auth/gmail.send']
10
});
```
### 2. Initiate OAuth flow for users
[Section titled “2. Initiate OAuth flow for users”](#2-initiate-oauth-flow-for-users)
When users want to connect their accounts, create a connected account and redirect them to complete OAuth:
```javascript
1
// Create a connected account for a user
2
const connectedAccount = await agentConnect.accounts.create({
3
connection_id: gmailConnection.id,
4
identifier: 'user_123',
5
identifier_type: 'user_id'
6
});
7
8
// Generate OAuth authorization URL
9
const authUrl = await agentConnect.accounts.getAuthUrl(connectedAccount.id);
10
// Redirect user to authUrl to authenticate with the provider
```
### 3. Handle OAuth callback
[Section titled “3. Handle OAuth callback”](#3-handle-oauth-callback)
After the user authorizes your application, the provider redirects back with an authorization code. Agent Auth automatically exchanges this code for access and refresh tokens:
```javascript
1
// Agent Auth handles the OAuth callback and token exchange
2
// Tokens are securely stored and automatically refreshed when needed
3
const account = await agentConnect.accounts.get(connectedAccount.id);
4
// account.status will be 'active' once authentication is complete
```
## Supported providers
[Section titled “Supported providers”](#supported-providers)
Agent Auth supports OAuth authentication for a wide range of popular business applications:
Communication
* Gmail (Google Workspace)
* Outlook (Microsoft 365)
* Slack
* Microsoft Teams
* Discord
Productivity
* Google Calendar
* Microsoft Calendar
* Google Drive
* OneDrive
* Notion
Project Management
* Jira
* Asana
* Trello
* Monday.com
* Linear
Development
* GitHub
* GitLab
* Bitbucket
* Figma
* Vercel
## Common authentication scenarios
[Section titled “Common authentication scenarios”](#common-authentication-scenarios)
### Multi-provider authentication
[Section titled “Multi-provider authentication”](#multi-provider-authentication)
Enable users to connect multiple third-party accounts in your application:
```javascript
1
// Allow users to authenticate with both Gmail and Slack
2
const gmailAccount = await agentConnect.accounts.create({
3
connection_id: gmailConnection.id,
4
identifier: 'user_123',
5
identifier_type: 'user_id'
6
});
7
8
const slackAccount = await agentConnect.accounts.create({
9
connection_id: slackConnection.id,
10
identifier: 'user_123',
11
identifier_type: 'user_id'
12
});
13
14
// Generate OAuth URLs for each provider
15
const gmailAuthUrl = await agentConnect.accounts.getAuthUrl(gmailAccount.id);
16
const slackAuthUrl = await agentConnect.accounts.getAuthUrl(slackAccount.id);
```
### Organization-level connections
[Section titled “Organization-level connections”](#organization-level-connections)
Authenticate once for an entire organization:
```javascript
1
// Create organization-level connection for shared access
2
const orgConnection = await agentConnect.accounts.create({
3
connection_id: jiraConnection.id,
4
identifier: 'org_456',
5
identifier_type: 'org_id'
6
});
7
8
// All users in the organization can access this connection
9
const authUrl = await agentConnect.accounts.getAuthUrl(orgConnection.id);
```
### Token lifecycle management
[Section titled “Token lifecycle management”](#token-lifecycle-management)
Agent Auth automatically handles token refresh and expiration:
```javascript
1
// Retrieve connected account - tokens are automatically refreshed if expired
2
const account = await agentConnect.accounts.get(connectedAccount.id);
3
4
// Check authentication status
5
if (account.status === 'active') {
6
// User is authenticated and tokens are valid
7
} else if (account.status === 'expired') {
8
// Re-authentication required
9
const reAuthUrl = await agentConnect.accounts.getAuthUrl(account.id);
10
}
```
## Key benefits
[Section titled “Key benefits”](#key-benefits)
### Developer experience
[Section titled “Developer experience”](#developer-experience)
* **Unified authentication API**: Single interface for OAuth across all providers
* **Automatic token refresh**: No manual token lifecycle management required
* **Pre-built OAuth flows**: Skip complex OAuth implementation for each provider
* **Multi-language SDKs**: Support for popular programming languages
* **Standardized error handling**: Consistent error responses across providers
### Security and compliance
[Section titled “Security and compliance”](#security-and-compliance)
* **OAuth 2.0 standard**: Industry-standard authentication protocol
* **Encrypted token storage**: Secure storage and transmission of access tokens
* **Automatic token rotation**: Refresh tokens automatically to minimize exposure
* **Audit logging**: Complete audit trail of authentication events
* **SOC 2 certified**: Enterprise-grade security standards
## Authentication options
[Section titled “Authentication options”](#authentication-options)
Agent Auth supports multiple authentication approaches:
### Scalekit-managed OAuth
[Section titled “Scalekit-managed OAuth”](#scalekit-managed-oauth)
Use Scalekit’s shared OAuth applications for quick setup:
* **Fast setup**: Get started in minutes without registering OAuth apps
* **Shared credentials**: Pre-configured OAuth credentials for all providers
* **Zero configuration**: No need to manage client IDs or secrets
* **Perfect for**: Development, testing, proof of concepts
### Bring Your Own OAuth (BYOO)
[Section titled “Bring Your Own OAuth (BYOO)”](#bring-your-own-oauth-byoo)
Use your own OAuth applications for complete control:
* **Custom branding**: Users see your application name and logo during OAuth
* **Higher rate limits**: Dedicated quotas for your OAuth application
* **Direct relationships**: Establish direct OAuth connections with providers
* **Enhanced control**: Full control over OAuth scopes and permissions
* **Perfect for**: Production applications, enterprise customers
## Getting started
[Section titled “Getting started”](#getting-started)
Ready to start using Agent Auth? Here’s what you need to do:
[Quickstart Guide ](/agent-auth/quickstart)
[Authentication Flows ](/agent-auth/authentication/auth-flows-comparison)
[Providers ](/agent-auth/providers)
## Support and resources
[Section titled “Support and resources”](#support-and-resources)
### Documentation
[Section titled “Documentation”](#documentation)
* **Authentication guides**: Step-by-step OAuth integration guides
* **API reference**: Complete authentication API documentation
* **SDK documentation**: Language-specific authentication examples
* **Best practices**: Security and token management guidelines
### Community and support
[Section titled “Community and support”](#community-and-support)
* **Developer community**: Join other developers using Agent Auth
* **Support portal**: Get help with authentication issues
* **Professional services**: Expert assistance for complex OAuth integrations
Note
**Ready to get started?** Check out our [Quickstart Guide](/agent-auth/quickstart) to implement your first OAuth integration with Agent Auth in minutes.
Agent Auth simplifies third-party authentication so you can focus on building features instead of managing OAuth flows. Start building today and provide seamless authentication experiences for your users.
---
# DOCUMENT BOUNDARY
---
# Providers
> Learn about third-party application providers supported by Agent Auth and how they enable tool execution across different platforms.
Providers in Agent Auth represent third-party applications that your users can connect to and interact with through Scalekit’s unified API. Each provider offers a set of tools and capabilities that can be executed on behalf of connected users.
## What are providers?
[Section titled “What are providers?”](#what-are-providers)
Providers are pre-configured integrations with popular third-party applications that enable your users to:
* **Connect their accounts** using secure authentication methods
* **Execute tools and actions** through a unified API interface
* **Access data and functionality** from external applications
* **Maintain secure connections** with proper authorization scopes
## Supported providers
[Section titled “Supported providers”](#supported-providers)
[Browse all agent connectors ](/guides/integrations/agent-connectors)
Next, learn how to configure [Connections](/agent-auth/connections) for your chosen providers to enable user authentication and tool execution.
---
# DOCUMENT BOUNDARY
---
# Invoke tools for your AI agent
> Execute tools directly, customize their behavior with modifiers, and build agentic workflows where LLMs drive tool selection.
Agent Auth supports three approaches to tool calling: execute tools directly with explicit parameters, customize tool behavior with pre- and post-modifiers, or let an LLM select and invoke tools automatically based on user input.
## Direct tool execution
[Section titled “Direct tool execution”](#direct-tool-execution)
Using Scalekit SDK, you can execute any action on behalf of a user using the following parameters:
* user context
* `tool_name`
* `tool_input_parameters`
- Python
```python
1
# Fetch recent emails
2
tool_response = actions.execute_tool(
3
# tool input parameters
4
tool_input={
5
'query': 'is:unread',
6
'max_results': 5
7
},
8
# tool name to execute
9
tool_name='gmail_fetch_mails',
10
# connected_account gives the user context
11
connected_account_id=connected_account.id,
12
)
13
14
print(f'Recent emails: {tool_response.result}')
```
- Node.js
```typescript
1
// Fetch recent emails
2
const toolResponse = await actions.executeTool({
3
// tool name to execute
4
toolName: 'gmail_fetch_mails',
5
// connectedAccountId from a prior getOrCreateConnectedAccount call
6
connectedAccountId: 'your_connected_account_id',
7
// tool input parameters
8
toolInput: {
9
query: 'is:unread',
10
max_results: 5,
11
},
12
});
13
14
console.log('Recent emails:', toolResponse.result);
```
## Customize with modifiers
[Section titled “Customize with modifiers”](#customize-with-modifiers)
Tool modifiers intercept and modify tool inputs and outputs using decorators.
* **Pre-modifiers**: Modify tool inputs before execution
* **Post-modifiers**: Modify tool outputs after execution
Common uses
* Reduce response size to prevent LLM context overloading
* Filter emails to unread only
* Add consistent parameters
* Transform data formats
### Pre-modifiers
[Section titled “Pre-modifiers”](#pre-modifiers)
Pre-modifiers modify tool inputs before execution to enforce consistent filters, add security constraints, override LLM decisions with required behavior, or set default configurations.
Example: Gmail unread filter
```python
1
from scalekit.actions.models.tool_input_output import ToolInput
2
3
# For example, we can modify the query to only fetch unread emails
4
# regardless of what the user asks for or what the LLM determines.
5
@actions.pre_modifier(tool_names=["gmail_fetch_mails"])
6
def gmail_pre_modifier(tool_input: ToolInput):
7
tool_input['query'] = 'is:unread'
8
return tool_input
```
This modifier:
* Intercepts all calls to `gmail_fetch_mails`
* Forces the query to always search for unread emails only
* Ensures consistent behavior regardless of user input or LLM interpretation
**Multiple tools example**
```python
1
@actions.pre_modifier(tool_names=["gmail_fetch_mails", "gmail_search_emails"])
2
def email_security_modifier(tool_input: ToolInput):
3
# Add security constraints to all email operations
4
tool_input['include_spam'] = False
5
tool_input['max_results'] = min(tool_input.get('max_results', 10), 50)
6
return tool_input
```
### Post-modifiers
[Section titled “Post-modifiers”](#post-modifiers)
Post-modifiers modify tool outputs after execution to reduce token usage, transform formats for LLM consumption, extract specific data, or standardize output structure.
Response format
Post-modifiers must always return a dictionary with a `"response"` key: `{"response": your_data}`
Example: Gmail response filtering
```python
1
from scalekit.actions.models.tool_input_output import ToolOutput
2
3
# Sometimes, the tool output needs to be modified in a deterministic way after the tool is executed.
4
# For example, we can modify the output to only return the first email snippet regardless of what the tool returns.
5
# This is an effective way to reduce the amount of data that is returned to the LLM to save on tokens.
6
@actions.post_modifier(tool_names=["gmail_fetch_mails"])
7
def gmail_post_modifier(output: ToolOutput):
8
# Only return the first email snippet
9
# Should return a dict
10
# Response should be a dict with a key 'response'
11
for snippet in output['messages']:
12
print(f"Email snippet: {snippet['snippet']}")
13
return {"response": output['messages'][0]['snippet']}
```
This modifier:
* Processes the response from `gmail_fetch_mails`
* Extracts only the first email snippet instead of returning all emails
* Reduces token usage by sending minimal data to the LLM
## Agentic tool calling
[Section titled “Agentic tool calling”](#agentic-tool-calling)
Let an LLM determine which tool to call and with what parameters based on user input. This quickstart uses LangChain to build an agent that authenticates a user with Gmail and fetches their last 5 unread emails.
**Prerequisites**: Scalekit API credentials (Client ID and Client Secret) and a Python development environment.
1. ### Set up your environment
[Section titled “Set up your environment”](#set-up-your-environment)
Install the Scalekit Python SDK and initialize the client with your API credentials:
```sh
pip install scalekit-sdk-python langchain
```
```python
import scalekit.client
import os
scalekit_client = scalekit.client.ScalekitClient(
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit_client.actions
```
2. ### Create a connected account
[Section titled “Create a connected account”](#create-a-connected-account)
Authorize a user to access their Gmail account by creating a connected account. This represents the user’s connection to their Gmail account:
```python
1
# Create a connected account for user if it doesn't exist already
2
response = actions.get_or_create_connected_account(
3
connection_name="gmail",
4
identifier="user_123"
5
)
6
connected_account = response.connected_account
7
8
print(f'Connected account created: {connected_account.id}')
```
3. ### Authenticate the user
[Section titled “Authenticate the user”](#authenticate-the-user)
For Scalekit to execute tools on behalf of the user, the user must grant authorization to access their Gmail account. Scalekit automatically handles the entire OAuth workflow, including token refresh.
```python
1
# If the user hasn't yet authorized the gmail connection or if the user's access token is expired,
2
# generate a magic link and redirect the user to this link so that the user can complete authorization
3
if(connected_account.status != "ACTIVE"):
4
link_response = actions.get_authorization_link(
5
connection_name="gmail",
6
identifier="user_123"
7
)
8
print(f"🔗click on the link to authorize gmail", link_response.link)
9
input(f"⎆ Press Enter after authorizing gmail...")
10
11
# In a real app, redirect the user to this URL so that the user can complete the authentication process for their gmail account
```
4. ### Build a LangChain agent
[Section titled “Build a LangChain agent”](#build-a-langchain-agent)
Build a simple agent that fetches the last 5 unread emails from the user’s inbox and generates a summary.
```python
1
from langchain_core.prompts import SystemMessagePromptTemplate, MessagesPlaceholder, HumanMessagePromptTemplate,PromptTemplate, ChatPromptTemplate
2
3
# use scalekit SDK to fetch all GMAIL tools in langchain format
4
tools = actions.langchain.get_tools(
5
identifier=identifier,
6
providers = ["GMAIL"], # all tools for provider used by default
7
page_size=100
8
)
9
10
prompt = ChatPromptTemplate.from_messages([
11
SystemMessagePromptTemplate(prompt=PromptTemplate(input_variables=[], template="You are a helpful assistant. Use tools if needed")),
12
MessagesPlaceholder(variable_name="chat_history", optional=True),
13
HumanMessagePromptTemplate(prompt=PromptTemplate(input_variables=["input"], template="{input}")),
14
MessagesPlaceholder(variable_name="agent_scratchpad")
15
])
16
17
llm = ChatOpenAI(model="gpt-4o")
18
agent = create_openai_tools_agent(llm, tools, prompt)
19
agent_executor = AgentExecutor(agent=agent, tools=tools,verbose=True)
20
result = agent_executor.invoke({"input":"fetch my last 5 unread emails and summarize it"}
21
)
```
## Next steps
[Section titled “Next steps”](#next-steps)
For more detailed framework-specific implementations, explore the AI framework guides:
[LangChain Framework ](/agent-auth/frameworks/langchain)
[Google ADK Framework ](/agent-auth/frameworks/google-adk)
[OpenClaw ](/agent-auth/openclaw)
---
# DOCUMENT BOUNDARY
---
# Authorize a user
> Learn how to authorize users for successful tool execution with Agent Auth.
Scalekit provides a completely managed authentication platform to handle complex OAuth2.0, API Keys, Bearer Tokens and any other API authentication protocols required by third party applications to execute tool calls on behalf of users.
This managed authentication handling enables you to build powerful agents without having to worry about handling user authentication and API authentication across different applications like Salesforce, Hubspot, GMail, Google Calendar etc.
## Authorize a user
[Section titled “Authorize a user”](#authorize-a-user)
If you are building an agent that needs to execute actions on behalf of a user, your agent needs to get authorization from user to give access to their application.
The following code sample helps your agent complete user authorization required to make a successful authenticated tool call.
* Python
```python
1
link_response = actions.get_authorization_link(
2
connection_name="gmail", # connection name to which the user needs to grant access
3
identifier="user_123" # unique user id
4
)
5
print(f"click on the link to authorize gmail", link_response.link)
6
input(f"Press Enter after authorizing gmail...")
```
* Node.js
```typescript
1
const linkResponse = await actions.getAuthorizationLink({
2
connectionName: 'gmail', // connection name to which the user needs to grant access
3
identifier: 'user_123', // unique user id
4
});
5
console.log('click on the link to authorize gmail', linkResponse.link);
6
// In production, redirect the user to linkResponse.link to complete the OAuth flow
```
## Check Authorization Status
[Section titled “Check Authorization Status”](#check-authorization-status)
If you would like to check whether the user has completed authorization for a given application,
* Python
```python
1
response = actions.get_or_create_connected_account(
2
connection_name="gmail",
3
identifier="user_123"
4
)
5
connected_account = response.connected_account
6
print(f"Authorization status of the connected account", connected_account.status)
```
* Node.js
```typescript
1
const response = await actions.getOrCreateConnectedAccount({
2
connectionName: 'gmail',
3
identifier: 'user_123',
4
});
5
const connectedAccount = response.connectedAccount;
6
console.log('Authorization status of the connected account', connectedAccount?.status);
```
---
# DOCUMENT BOUNDARY
---
# Pre and Post Processors
> Learn how to create pre and post processor workflows that are run before or after tool execution with Agent Auth.
Custom pre and post processors are a way to create custom workflows that are run before or after tool execution with Agent Auth. They are useful for:
* Validating and transforming input data
* Processing and Formatting output data
* Adding additional context to the tool execution
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# Custom Tools
> Learn how to create custom tools with Agent Auth.
# Custom Tools
[Section titled “Custom Tools”](#custom-tools)
Custom tools are a way to create custom tools that can be used in Agent Auth.
## Usage
[Section titled “Usage”](#usage)
---
# DOCUMENT BOUNDARY
---
# Tools Overview
> Learn about tools in Agent Auth - the standardized functions that enable you to perform actions across different third-party providers.
LLMs today are very powerful reasoning and answering machines but their ability is restricted to data sets that they are trained upon and cannot natively interact with web services or saas applications. Tool Calling or Function Calling is how you extend the capabilities of these models to interact and take actions in third party applications on behalf of the users.
For example, if you would like to build an email summarizer agent, there are a few challenges that you need to tackle:
1. How to give agents access to gmail
2. How to authorize these agents access to my gmail account
3. What should be the appropriate input parameters to access gmail based on user context and query
Agent Auth product solves these problems by giving you simple abstractions using our SDK to help you give additional capabilities to the agents you are building regardless of the underlying model and agent framework in three simple steps.
1. Use Scalekit SDK to fetch all the appropriate tools
2. Complete user authorization handling in one single line of code
3. Use Scalekit’s optimized tool metadata and pass it to the underlying model for optimal tool selection and input parameters.
## Tool Metadata
[Section titled “Tool Metadata”](#tool-metadata)
Every tool in Agent Auth follows a consistent structure with a name, description and structured input and output schema. Agentic frameworks like Langchain can work with the underlying LLMs to select the right tool to solve the user’s query based on the tool metadata.
### Sample Tool definition
[Section titled “Sample Tool definition”](#sample-tool-definition)
```json
1
{
2
"name": "gmail_send_email",
3
"display_name": "Send Email",
4
"description": "Send an email message to one or more recipients",
5
"provider": "gmail",
6
"category": "communication",
7
"input_schema": {
8
"type": "object",
9
"properties": {
10
"to": {
11
"type": "array",
12
"items": {"type": "string", "format": "email"},
13
"description": "Email addresses of recipients"
14
},
15
"subject": {
16
"type": "string",
17
"description": "Email subject line"
18
},
19
"body": {
20
"type": "string",
21
"description": "Email body content"
22
}
23
},
24
"required": ["to", "subject", "body"]
25
},
26
"output_schema": {
27
"type": "object",
28
"properties": {
29
"message_id": {
30
"type": "string",
31
"description": "Unique identifier for the sent message"
32
},
33
"status": {
34
"type": "string",
35
"enum": ["sent", "queued", "failed"],
36
"description": "Status of the email sending operation"
37
}
38
}
39
}
40
}
```
## Best practices
[Section titled “Best practices”](#best-practices)
1. **Tool Selection:** Even though tools provide additional capabilities to the agents, the real challenge in leveraging underlying LLMs capability to select the right tool to solve the job at hand. And LLMs do a poor job when you throw all the available tools you have at your disposal and ask LLMs to pick the right tool. So, be sure to limit the number of tools that you provide in the context to the LLM so that they do a good job in tool selection and filling in the appropriate input parameters to actually execute a certain action successfully.
2. **Add deterministic overrides in undeterministic workflows:** Because LLMs are unpredictable super machines, do not trust them to reliably execute the same workflow every single time in the exact same manner. If your agent has some deterministic patterns or workflows, use the pre-execution modifiers to always set exact input parameters for a given tool. For example, if your agent always reads only unread emails, create a pre-execution modifier to add `is:unread` to the query input param while fetching emails using gmail\_fetch\_emails tool.
3. **Context Window Awareness:** Similar to the point above, always be conscious of overloading context window of the underlying models. Don’t send the entire tool execution response/output to the underlying model for processing the execution response. Use the post-execution modifiers to select only the required and necessary fields in the tool output response before sending the data to the LLMs.
***
Tools are the fundamental building blocks through which you can give real world capabilities for the agents you are building. By understanding how to use them effectively, you can build sophisticated agents that seamlessly connect your application to the tools your users already love.
---
# DOCUMENT BOUNDARY
---
# Proxy Tools
> Learn how to make direct API calls to providers using Agent Auth's proxy tools.
Custom tool definitions allow you to create specialized tools tailored to your specific business needs. You can combine multiple provider tools, add custom logic, and create reusable workflows that go beyond standard tool functionality.
## What are custom tools?
[Section titled “What are custom tools?”](#what-are-custom-tools)
Custom tools are user-defined functions that:
* **Extend existing tools**: Build on top of standard provider tools
* **Combine multiple operations**: Create workflows that use multiple tools
* **Add business logic**: Include custom validation, processing, and formatting
* **Create reusable patterns**: Standardize common operations across your team
* **Integrate with external systems**: Connect to your own APIs and services
## Custom tool structure
[Section titled “Custom tool structure”](#custom-tool-structure)
Every custom tool follows a standardized structure:
```javascript
1
{
2
name: 'custom_tool_name',
3
display_name: 'Custom Tool Display Name',
4
description: 'Description of what the tool does',
5
category: 'custom',
6
provider: 'custom',
7
input_schema: {
8
type: 'object',
9
properties: {
10
// Define input parameters
11
},
12
required: ['required_param']
13
},
14
output_schema: {
15
type: 'object',
16
properties: {
17
// Define output format
18
}
19
},
20
implementation: async (parameters, context) => {
21
// Custom tool logic
22
return result;
23
}
24
}
```
## Creating custom tools
[Section titled “Creating custom tools”](#creating-custom-tools)
### Basic custom tool
[Section titled “Basic custom tool”](#basic-custom-tool)
Here’s a simple custom tool that sends a welcome email:
```javascript
1
const sendWelcomeEmail = {
2
name: 'send_welcome_email',
3
display_name: 'Send Welcome Email',
4
description: 'Send a personalized welcome email to new users',
5
category: 'communication',
6
provider: 'custom',
7
input_schema: {
8
type: 'object',
9
properties: {
10
user_name: {
11
type: 'string',
12
description: 'Name of the new user'
13
},
14
user_email: {
15
type: 'string',
16
format: 'email',
17
description: 'Email address of the new user'
18
},
19
company_name: {
20
type: 'string',
21
description: 'Name of the company'
22
}
23
},
24
required: ['user_name', 'user_email', 'company_name']
25
},
26
output_schema: {
27
type: 'object',
28
properties: {
29
message_id: {
30
type: 'string',
31
description: 'ID of the sent email'
32
},
33
status: {
34
type: 'string',
35
enum: ['sent', 'failed'],
36
description: 'Status of the email'
37
}
38
}
39
},
40
implementation: async (parameters, context) => {
41
const { user_name, user_email, company_name } = parameters;
42
43
// Generate personalized email content
44
const emailBody = `
45
Welcome to ${company_name}, ${user_name}!
46
47
We're excited to have you join our team. Here are some next steps:
48
49
1. Complete your profile setup
50
2. Join our Slack workspace
51
3. Schedule a meeting with your manager
52
53
If you have any questions, don't hesitate to reach out!
54
55
Best regards,
56
The ${company_name} Team
57
`;
58
59
// Send email using standard email tool
60
const result = await context.tools.execute({
61
tool: 'send_email',
62
parameters: {
63
to: [user_email],
64
subject: `Welcome to ${company_name}!`,
65
body: emailBody
66
}
67
});
68
69
return {
70
message_id: result.message_id,
71
status: result.status === 'sent' ? 'sent' : 'failed'
72
};
73
}
74
};
```
### Multi-step workflow tool
[Section titled “Multi-step workflow tool”](#multi-step-workflow-tool)
Create a tool that combines multiple operations:
```javascript
1
const createProjectWorkflow = {
2
name: 'create_project_workflow',
3
display_name: 'Create Project Workflow',
4
description: 'Create a complete project setup with Jira project, Slack channel, and team notifications',
5
category: 'project_management',
6
provider: 'custom',
7
input_schema: {
8
type: 'object',
9
properties: {
10
project_name: {
11
type: 'string',
12
description: 'Name of the project'
13
},
14
project_key: {
15
type: 'string',
16
description: 'Project key for Jira'
17
},
18
team_members: {
19
type: 'array',
20
items: { type: 'string', format: 'email' },
21
description: 'Team member email addresses'
22
},
23
project_description: {
24
type: 'string',
25
description: 'Project description'
26
}
27
},
28
required: ['project_name', 'project_key', 'team_members']
29
},
30
output_schema: {
31
type: 'object',
32
properties: {
33
jira_project_id: { type: 'string' },
34
slack_channel_id: { type: 'string' },
35
notifications_sent: { type: 'number' }
36
}
37
},
38
implementation: async (parameters, context) => {
39
const { project_name, project_key, team_members, project_description } = parameters;
40
41
try {
42
// Step 1: Create Jira project
43
const jiraProject = await context.tools.execute({
44
tool: 'create_jira_project',
45
parameters: {
46
key: project_key,
47
name: project_name,
48
description: project_description,
49
project_type: 'software'
50
}
51
});
52
53
// Step 2: Create Slack channel
54
const slackChannel = await context.tools.execute({
55
tool: 'create_channel',
56
parameters: {
57
name: `${project_key.toLowerCase()}-team`,
58
topic: `Discussion for ${project_name}`,
59
is_private: false
60
}
61
});
62
63
// Step 3: Send notifications to team members
64
let notificationCount = 0;
65
for (const member of team_members) {
66
try {
67
await context.tools.execute({
68
tool: 'send_email',
69
parameters: {
70
to: [member],
71
subject: `New Project: ${project_name}`,
72
body: `
73
You've been added to the new project "${project_name}".
74
75
Jira Project: ${jiraProject.project_url}
76
Slack Channel: #${slackChannel.channel_name}
77
78
Please join the Slack channel to start collaborating!
79
`
80
}
81
});
82
notificationCount++;
83
} catch (error) {
84
console.error(`Failed to send notification to ${member}:`, error);
85
}
86
}
87
88
// Step 4: Post welcome message to Slack channel
89
await context.tools.execute({
90
tool: 'send_message',
91
parameters: {
92
channel: `#${slackChannel.channel_name}`,
93
text: `<� Welcome to ${project_name}! This channel is for project discussion and updates.`
94
}
95
});
96
97
return {
98
jira_project_id: jiraProject.project_id,
99
slack_channel_id: slackChannel.channel_id,
100
notifications_sent: notificationCount
101
};
102
103
} catch (error) {
104
throw new Error(`Project creation failed: ${error.message}`);
105
}
106
}
107
};
```
### Data processing tool
[Section titled “Data processing tool”](#data-processing-tool)
Create a tool that processes and analyzes data:
```javascript
1
const generateTeamReport = {
2
name: 'generate_team_report',
3
display_name: 'Generate Team Report',
4
description: 'Generate a comprehensive team performance report from multiple sources',
5
category: 'analytics',
6
provider: 'custom',
7
input_schema: {
8
type: 'object',
9
properties: {
10
team_members: {
11
type: 'array',
12
items: { type: 'string', format: 'email' },
13
description: 'Team member email addresses'
14
},
15
start_date: {
16
type: 'string',
17
format: 'date',
18
description: 'Report start date'
19
},
20
end_date: {
21
type: 'string',
22
format: 'date',
23
description: 'Report end date'
24
},
25
include_calendar: {
26
type: 'boolean',
27
default: true,
28
description: 'Include calendar analysis'
29
}
30
},
31
required: ['team_members', 'start_date', 'end_date']
32
},
33
output_schema: {
34
type: 'object',
35
properties: {
36
report_url: { type: 'string' },
37
summary: { type: 'object' },
38
sent_to: { type: 'array', items: { type: 'string' } }
39
}
40
},
41
implementation: async (parameters, context) => {
42
const { team_members, start_date, end_date, include_calendar } = parameters;
43
44
// Fetch Jira issues assigned to team members
45
const jiraIssues = await context.tools.execute({
46
tool: 'fetch_issues',
47
parameters: {
48
jql: `assignee in (${team_members.join(',')}) AND created >= ${start_date} AND created <= ${end_date}`,
49
fields: ['summary', 'status', 'assignee', 'created', 'resolved']
50
}
51
});
52
53
// Fetch calendar events if requested
54
let calendarData = null;
55
if (include_calendar) {
56
calendarData = await context.tools.execute({
57
tool: 'fetch_events',
58
parameters: {
59
start_date: start_date,
60
end_date: end_date,
61
attendees: team_members
62
}
63
});
64
}
65
66
// Process and analyze data
67
const report = {
68
period: { start_date, end_date },
69
team_size: team_members.length,
70
issues: {
71
total: jiraIssues.issues.length,
72
completed: jiraIssues.issues.filter(i => i.status === 'Done').length,
73
in_progress: jiraIssues.issues.filter(i => i.status === 'In Progress').length
74
},
75
meetings: calendarData ? {
76
total: calendarData.events.length,
77
hours: calendarData.events.reduce((acc, event) => acc + event.duration, 0)
78
} : null
79
};
80
81
// Generate HTML report
82
const htmlReport = `
83
84
Team Report - ${start_date} to ${end_date}
85
86
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. Navigate to **Tools** in your Agent Auth dashboard
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
---
# 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/auth-methods/enterprise-sso/#identify-and-enforce-sso-for-organization-users).
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 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.
**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.
#### 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> getAllUsers(HttpServletRequest request) {
13
Map user = (Map) request.getAttribute("user");
14
15
// Check for admin role
16
if (!hasRole(user, "admin")) {
17
return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
18
}
19
20
String orgId = (String) user.get("organizationId");
21
List users = userService.getAllUsersForOrg(orgId);
22
return ResponseEntity.ok(users);
23
}
24
25
@PostMapping("/api/admin/invite-user")
26
public ResponseEntity inviteUser(
27
@RequestBody InviteUserRequest request,
28
HttpServletRequest httpRequest
29
) {
30
Map user = (Map) httpRequest.getAttribute("user");
31
32
// Allow admins or managers to invite users
33
if (!hasRole(user, "admin") && !hasRole(user, "manager")) {
34
return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
35
}
36
37
String orgId = (String) user.get("organizationId");
38
Invitation invitation = userService.createInvitation(request, orgId);
39
return ResponseEntity.ok(invitation);
40
}
41
}
```
## Verify user’s permissions to allow specific actions
[Section titled “Verify user’s permissions to allow specific actions”](#verify-users-permissions-to-allow-specific-actions)
Permission-based access control provides granular control over specific actions and resources within your application. While roles offer broad access patterns, permissions allow you to define exactly what operations users can perform, enabling precise security controls and the principle of least privilege.
Note
Permissions are typically formatted as `resource:action` (e.g., `projects:create`, `users:read`, `reports:delete`) to provide clear, consistent naming conventions that make your access control logic more readable and maintainable.
* Node.js
Permission-based access control
```javascript
17 collapsed lines
1
// Helper function to check permissions
2
function hasPermission(user, requiredPermission) {
3
return user.permissions && user.permissions.includes(requiredPermission);
4
}
5
6
// Middleware to require specific permissions
7
function requirePermission(permission) {
8
return (req, res, next) => {
9
if (!hasPermission(req.user, permission)) {
10
return res.status(403).json({
11
error: `Access denied. Required permission: ${permission}`
12
});
13
}
14
next();
15
};
16
}
17
18
// Protected routes with permission checks
19
app.get('/api/projects', validateAndExtractAuth, requirePermission('projects:read'), (req, res) => {
20
// User has projects:read permission - allow access
21
res.json(getProjects(req.user.organizationId));
22
});
23
24
app.post('/api/projects', validateAndExtractAuth, requirePermission('projects:create'), (req, res) => {
25
// User has projects:create permission - allow creation
26
const newProject = createProject(req.body, req.user.organizationId);
27
res.json(newProject);
28
});
29
30
// Multiple permission check
31
app.delete('/api/projects/:id', validateAndExtractAuth, (req, res) => {
32
const user = req.user;
33
34
// Check if user has either admin role or specific delete permission
35
if (!hasPermission(user, 'projects:delete') && !user.roles.includes('admin')) {
36
return res.status(403).json({ error: 'Cannot delete projects' });
37
}
38
39
deleteProject(req.params.id, user.organizationId);
40
res.json({ success: true });
41
});
```
* Python
Permission-based access control
```python
17 collapsed lines
1
# Helper function to check permissions
2
def has_permission(user, required_permission):
3
permissions = user.get('permissions', [])
4
return required_permission in permissions
5
6
# Decorator to require specific permissions
7
def require_permission(permission):
8
def decorator(f):
9
@wraps(f)
10
def decorated_function(*args, **kwargs):
11
user = getattr(request, 'user', {})
12
if not has_permission(user, permission):
13
return jsonify({'error': f'Access denied. Required permission: {permission}'}), 403
14
return f(*args, **kwargs)
15
return decorated_function
16
return decorator
17
18
# Protected routes with permission checks
19
@app.route('/api/projects')
20
@validate_and_extract_auth
21
@require_permission('projects:read')
22
def get_projects():
23
# User has projects:read permission - allow access
24
return jsonify(get_projects_for_org(request.user['organization_id']))
25
26
@app.route('/api/projects', methods=['POST'])
27
@validate_and_extract_auth
28
@require_permission('projects:create')
29
def create_project():
30
# User has projects:create permission - allow creation
31
new_project = create_project_for_org(request.json, request.user['organization_id'])
32
return jsonify(new_project)
33
34
# Multiple permission check
35
@app.route('/api/projects/', methods=['DELETE'])
36
@validate_and_extract_auth
37
def delete_project(project_id):
38
user = request.user
39
40
# Check if user has either admin role or specific delete permission
41
if not has_permission(user, 'projects:delete') and 'admin' not in user.get('roles', []):
42
return jsonify({'error': 'Cannot delete projects'}), 403
43
44
delete_project_from_org(project_id, user['organization_id'])
45
return jsonify({'success': True})
```
* Go
Permission-based access control
```go
1
// Helper function to check permissions
2
func hasPermission(user map[string]interface{}, requiredPermission string) bool {
3
permissions, ok := user["permissions"].([]interface{})
4
if !ok {
5
return false
6
}
7
8
for _, perm := range permissions {
9
if permStr, ok := perm.(string); ok && permStr == requiredPermission {
10
return true
11
}
12
}
13
return false
14
}
15
16
// Middleware to require specific permissions
17
func requirePermission(permission 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 !hasPermission(user, permission) {
23
http.Error(w, fmt.Sprintf(`{"error": "Access denied. Required permission: %s"}`, permission), http.StatusForbidden)
24
return
25
}
26
27
next(w, r)
28
}
29
}
30
}
31
32
// Protected routes with permission checks
33
func getProjectsHandler(w http.ResponseWriter, r *http.Request) {
34
user := r.Context().Value("user").(map[string]interface{})
35
orgId := user["organization_id"].(string)
36
37
// User has projects:read permission - allow access
38
projects := getProjectsForOrg(orgId)
39
json.NewEncoder(w).Encode(projects)
40
}
41
42
func createProjectHandler(w http.ResponseWriter, r *http.Request) {
43
user := r.Context().Value("user").(map[string]interface{})
44
orgId := user["organization_id"].(string)
45
46
// User has projects:create permission - allow creation
47
var projectData map[string]interface{}
48
json.NewDecoder(r.Body).Decode(&projectData)
49
50
newProject := createProjectForOrg(projectData, orgId)
51
json.NewEncoder(w).Encode(newProject)
52
}
53
54
// Route setup with middleware
55
http.HandleFunc("/api/projects", validateAndExtractAuth(requirePermission("projects:read")(getProjectsHandler)))
56
http.HandleFunc("/api/projects/create", validateAndExtractAuth(requirePermission("projects:create")(createProjectHandler)))
```
* Java
Permission-based access control
```java
1
@RestController
2
public class ProjectController {
3
4
// Helper method to check permissions
5
private boolean hasPermission(Map user, String requiredPermission) {
6
List permissions = (List) user.get("permissions");
7
return permissions != null && permissions.contains(requiredPermission);
8
}
9
10
// Annotation-based permission checking
11
@GetMapping("/api/projects")
12
@PreAuthorize("hasPermission('projects:read')")
13
public ResponseEntity> getProjects(HttpServletRequest request) {
14
Map user = (Map) request.getAttribute("user");
15
String orgId = (String) user.get("organizationId");
16
17
// User has projects:read permission - allow access
18
List projects = projectService.getProjectsForOrg(orgId);
19
return ResponseEntity.ok(projects);
20
}
21
22
@PostMapping("/api/projects")
23
public ResponseEntity createProject(
24
@RequestBody CreateProjectRequest request,
25
HttpServletRequest httpRequest
26
) {
27
Map user = (Map) httpRequest.getAttribute("user");
28
29
// Check permission manually
30
if (!hasPermission(user, "projects:create")) {
31
return ResponseEntity.status(HttpStatus.FORBIDDEN)
32
.body(null);
33
}
34
35
String orgId = (String) user.get("organizationId");
36
Project newProject = projectService.createProject(request, orgId);
37
return ResponseEntity.ok(newProject);
38
}
39
40
@DeleteMapping("/api/projects/{projectId}")
41
public ResponseEntity> deleteProject(
42
@PathVariable String projectId,
43
HttpServletRequest request
44
) {
45
Map user = (Map) request.getAttribute("user");
46
List roles = (List) user.get("roles");
47
48
// Check if user has either admin role or specific delete permission
49
if (!hasPermission(user, "projects:delete") && !roles.contains("admin")) {
50
return ResponseEntity.status(HttpStatus.FORBIDDEN)
51
.body(Map.of("error", true));
52
}
53
54
String orgId = (String) user.get("organizationId");
55
projectService.deleteProject(projectId, orgId);
56
return ResponseEntity.ok(Map.of("success", true));
57
}
58
}
```
By implementing both role-based and permission-based access control, your application now has a comprehensive security framework that protects different routes and endpoints. You can combine both approaches to create fine-grained access control that matches your application’s specific requirements.
**Admin bypass pattern**: Allow users with `admin` role to bypass certain permission checks while maintaining granular control for other users
**Resource ownership pattern**: Combine role/permission checks with resource ownership verification (e.g., users can only edit their own projects unless they have admin role)
**Time-based access pattern**: Consider implementing time-based restrictions for sensitive operations, especially for roles with elevated permissions
Caution
Never implement authorization logic solely on the client side. Always perform server-side validation of roles and permissions, as client-side checks can be bypassed by malicious users.
---
# DOCUMENT BOUNDARY
---
# Role based access control (RBAC)
> Control what authenticated users can access in your application based on their roles and permissions
When users access features in your application, your app needs to control what actions they can perform. These permissions might be set by your app as defaults or by organization administrators. For example, in a project management application, you can allow some users to create projects while restricting others to only view existing projects. Role-based access control (RBAC) provides the framework to implement these permissions systematically.
After users authenticate through Scalekit, your application receives an access token containing their roles and permissions. Use this token to make authorization decisions and control access to features and resources.
Access tokens contain two key components for authorization:
**Roles** group related permissions together and define what users can do in your system. Common examples include Admin, Manager, Editor, and Viewer. Roles can inherit permissions from other roles, creating hierarchical access levels.
**Permissions** represent specific actions users can perform, formatted as `resource:action` patterns like `projects:create` or `tasks:read`. Use permissions for granular access control when you need precise control over individual capabilities.
Access token contents
```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", "tasks:assign"],
"sid": "ses_987654321098765432",
"sub": "usr_987654321098765432"
}
```
Scalekit automatically assigns the `admin` role to the first user in each organization and the `member` role to subsequent users. Your application uses the role and permission information from Scalekit to make final authorization decisions at runtime.
Start by defining the roles and permissions your application needs.
---
# DOCUMENT BOUNDARY
---
# Code samples
> Full stack auth code samples demonstrating complete authentication implementations with hosted login and session management
### [Full Stack Auth with Next.js](https://github.com/scalekit-inc/scalekit-nextjs-auth-example)
[Complete authentication solution for Next.js apps. Includes hosted login pages, session management, and protected routes](https://github.com/scalekit-inc/scalekit-nextjs-auth-example)
### [Full Stack Auth with FastAPI](https://github.com/scalekit-inc/scalekit-fastapi-auth-example)
[Authentication template for FastAPI projects. Featuring integrated user sessions, hosted login flow, and ready-to-use route protection specifically tailored for Python web backends.](https://github.com/scalekit-inc/scalekit-fastapi-auth-example)
### [Full Stack Auth with Flask](https://github.com/scalekit-inc/scalekit-flask-auth-example)
[Authentication template for Flask applications. Features session management, hosted login flow, and decorator-based route protection](https://github.com/scalekit-inc/scalekit-flask-auth-example)
### [Full Stack Auth with Django](https://github.com/scalekit-inc/scalekit-django-auth-example)
[Authentication template for Django projects. Features session management, hosted login flow, and middleware-based route protection](https://github.com/scalekit-inc/scalekit-django-auth-example)
### [Full Stack Auth with Express](https://github.com/scalekit-inc/scalekit-express-auth-example)
[Complete authentication solution for Express.js applications. Includes hosted login pages, session management, and middleware-protected routes](https://github.com/scalekit-inc/scalekit-express-auth-example)
### [Full Stack Auth with Spring Boot](https://github.com/scalekit-inc/scalekit-springboot-auth-example)
[End-to-end authentication for Java applications. Features Spring Security integration, hosted login, and session handling](https://github.com/scalekit-inc/scalekit-springboot-auth-example)
### [Full Stack Auth with Laravel](https://github.com/scalekit-inc/scalekit-laravel-auth-example)
[Complete authentication solution for Laravel applications. Includes hosted login pages, session management, and middleware-protected routes](https://github.com/scalekit-inc/scalekit-laravel-auth-example)
### End to end full stack auth demo
Coffee Desk App
Complete coffee shop management application with full stack. Features workspaces, organization switcher, and mulitple auth methods
[View demo](https://dashboard.coffeedesk.app/) | [View code](https://github.com/scalekit-inc/coffee-desk-demo)
---
# DOCUMENT BOUNDARY
---
# Implement logout
> Terminate user sessions across your application and Scalekit
When implementing logout functionality, you need to consider three session layers where user authentication state is maintained:
1. **Application session layer**: Your application stores session tokens (access tokens, refresh tokens, ID tokens) in browser cookies. You control this layer completely.
2. **Scalekit session layer**: Scalekit maintains a session for the user and stores their information. When users return to Scalekit’s authentication page, their information is remembered for a smoother experience.
3. **Identity provider session layer**: When users authenticate with external providers (for example, Okta through enterprise SSO), those providers maintain their own sessions. Users won’t be prompted to sign in again if they’re already signed into the provider.
This guide shows you how to clear the application session layer and invalidate the Scalekit session layer in a single logout endpoint.
1. ## Create a logout endpoint
[Section titled “Create a logout endpoint”](#create-a-logout-endpoint)
Create a `/logout` endpoint in your application that handles the complete logout flow: extracting the ID token, generating the Scalekit logout URL (which points to Scalekit’s `/oidc/logout` endpoint), clearing session cookies, and redirecting to Scalekit.
* Node.js
Express.js
```javascript
1
app.get('/logout', (req, res) => {
2
// Step 1: Extract the ID token (needed for Scalekit logout)
3
const idTokenHint = req.cookies.idToken;
4
const postLogoutRedirectUri = 'http://localhost:3000/login';
5
6
// Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
7
const logoutUrl = scalekit.getLogoutUrl(
8
idTokenHint, // ID token to invalidate
9
postLogoutRedirectUri // URL that scalekit redirects after session invalidation
10
);
11
12
// Step 3: Clear all session cookies
13
res.clearCookie('accessToken');
14
res.clearCookie('refreshToken');
15
res.clearCookie('idToken'); // Clear AFTER using it for logout URL
16
17
// Step 4: Redirect to Scalekit to invalidate the session
18
res.redirect(logoutUrl);
19
});
```
* Python
Flask
```python
1
from flask import request, redirect, make_response
2
from scalekit import LogoutUrlOptions
3
4
@app.route('/logout')
5
def logout():
6
# Step 1: Extract the ID token (needed for Scalekit logout)
7
id_token = request.cookies.get('idToken')
8
post_logout_redirect_uri = 'http://localhost:3000/login'
9
10
# Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
11
logout_url = scalekit_client.get_logout_url(
12
LogoutUrlOptions(
13
id_token_hint=id_token,
14
post_logout_redirect_uri=post_logout_redirect_uri
15
)
16
)
17
18
# Step 3: Create response and clear all session cookies
19
response = make_response(redirect(logout_url))
20
response.set_cookie('accessToken', '', max_age=0)
21
response.set_cookie('refreshToken', '', max_age=0)
22
response.set_cookie('idToken', '', max_age=0) # Clear AFTER using it for logout URL
23
24
# Step 4: Return response that redirects to Scalekit
25
return response
```
* Go
Gin
```go
1
func logoutHandler(c *gin.Context) {
2
// Step 1: Extract the ID token (needed for Scalekit logout)
3
idToken, _ := c.Cookie("idToken")
4
postLogoutRedirectURI := "http://localhost:3000/login"
5
6
// Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
7
logoutURL, err := scalekitClient.GetLogoutUrl(LogoutUrlOptions{
8
IdTokenHint: idToken,
9
PostLogoutRedirectUri: postLogoutRedirectURI,
10
})
11
if err != nil {
12
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
13
return
14
}
15
16
// Step 3: Clear all session cookies
17
c.SetCookie("accessToken", "", -1, "/", "", true, true)
18
c.SetCookie("refreshToken", "", -1, "/", "", true, true)
19
c.SetCookie("idToken", "", -1, "/", "", true, true) // Clear AFTER using it for logout URL
20
21
// Step 4: Redirect to Scalekit to invalidate the session
22
c.Redirect(http.StatusFound, logoutURL.String())
23
}
```
* Java
Spring Boot
```java
1
@GetMapping("/logout")
2
public void logout(HttpServletRequest request, HttpServletResponse response) throws IOException {
3
// Step 1: Extract the ID token (needed for Scalekit logout)
4
String idToken = request.getCookies() != null ?
5
Arrays.stream(request.getCookies())
6
.filter(c -> c.getName().equals("idToken"))
7
.findFirst()
8
.map(Cookie::getValue)
9
.orElse(null) : null;
10
11
String postLogoutRedirectUri = "http://localhost:3000/login";
12
13
// Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
14
LogoutUrlOptions options = new LogoutUrlOptions();
15
options.setIdTokenHint(idToken);
16
options.setPostLogoutRedirectUri(postLogoutRedirectUri);
17
URL logoutUrl = scalekitClient.authentication().getLogoutUrl(options);
18
19
// Step 3: Clear all session cookies with security attributes
20
Cookie accessTokenCookie = new Cookie("accessToken", null);
21
accessTokenCookie.setMaxAge(0);
22
accessTokenCookie.setPath("/");
23
accessTokenCookie.setHttpOnly(true);
24
accessTokenCookie.setSecure(true);
25
response.addCookie(accessTokenCookie);
26
27
Cookie refreshTokenCookie = new Cookie("refreshToken", null);
28
refreshTokenCookie.setMaxAge(0);
29
refreshTokenCookie.setPath("/");
30
refreshTokenCookie.setHttpOnly(true);
31
refreshTokenCookie.setSecure(true);
32
response.addCookie(refreshTokenCookie);
33
34
Cookie idTokenCookie = new Cookie("idToken", null);
35
idTokenCookie.setMaxAge(0);
36
idTokenCookie.setPath("/");
37
idTokenCookie.setHttpOnly(true);
38
idTokenCookie.setSecure(true);
39
response.addCookie(idTokenCookie); // Clear AFTER using it for logout URL
40
41
// Step 4: Redirect to Scalekit to invalidate the session
42
response.sendRedirect(logoutUrl.toString());
43
}
```
The logout flow clears cookies **AFTER** extracting the ID token and generating the logout URL. This ensures the ID token is available for Scalekit’s logout endpoint.
Why must logout be a browser redirect?
You must redirect to the `/oidc/logout` endpoint using a **browser redirect**, not through an API call. Redirecting the browser to Scalekit’s logout URL ensures the session cookie is automatically sent with the request, allowing Scalekit to correctly identify and end the user’s session.
2. ## Configure post-logout redirect URL
[Section titled “Configure post-logout redirect URL”](#configure-post-logout-redirect-url)
After users log out, Scalekit redirects them to the URL you specify in the `post_logout_redirect_uri` parameter. This URL must be registered in your Scalekit dashboard under **Dashboard > Authentication > Redirects > Post Logout URL**.
Scalekit only redirects to URLs from your allow list. This prevents unauthorized redirects and protects your users. If you need different redirect URLs for different applications, you can register multiple post-logout URLs in your dashboard.
Logout security checklist
* Extract the ID token BEFORE clearing cookies (needed for Scalekit logout)
* Clear all session cookies from your application
* Redirect to Scalekit’s logout endpoint to invalidate the session server-side
* Ensure your post-logout redirect URI is registered in the Scalekit dashboard
## Common logout scenarios
[Section titled “Common logout scenarios”](#common-logout-scenarios)
Which endpoint should I use for logout?
Use `/oidc/logout` (end\_session\_endpoint) for user logout functionality. This endpoint requires a browser redirect and clears the user’s session server-side.
Why must logout be a browser redirect?
You need to route to the `/oidc/logout` endpoint through a **browser redirect**, not with an API request. Redirecting the browser to Scalekit’s logout URL ensures the session cookie is sent automatically, so Scalekit can correctly locate and end the user’s session.
**❌ Doesn’t work - API call from frontend:**
```javascript
1
fetch('https://your-env.scalekit.dev/oidc/logout', {
2
method: 'POST',
3
body: JSON.stringify({ id_token_hint: idToken })
4
});
5
// Session cookie is NOT included, Scalekit can't identify the session
```
**✅ Works - Browser redirect:**
```javascript
1
const logoutUrl = scalekit.getLogoutUrl(idToken, postLogoutRedirectUri);
2
window.location.href = logoutUrl;
3
// Browser includes session cookies automatically
```
**Why:** Your user session is stored in an HttpOnly cookie. API requests from JavaScript or backend servers don’t include this cookie, so Scalekit can’t identify which session to terminate.
Session not clearing after logout?
If clicking login after logout bypasses the login screen and logs you back in automatically, check the following:
1. **Verify the logout method** - Open browser DevTools → Network tab and trigger logout:
* ✅ Type should show **“document”** (navigation)
* ❌ Type should **NOT** show “fetch” or “xhr”
* Check that the `Cookie` header is present in the request
2. **Check post-logout redirect URI** - Ensure it’s registered in **Dashboard > Authentication > Redirects > Post Logout URL**.
---
# DOCUMENT BOUNDARY
---
# Manage user sessions
> Store tokens safely with proper cookie security, validate on every request, and refresh with rotation to keep sessions secure
User sessions determine how long users stay signed in to your application. After users successfully authenticate, you receive session tokens that manage their access. These tokens control session duration, multi-device access, and cross-product authentication within your company’s ecosystem.
This guide shows you how to store these tokens securely with encryption and proper cookie attributes, validate them on every request, and refresh them transparently in middleware to maintain seamless user sessions.
Review the session management sequence
1. ## Store session tokens securely
[Section titled “Store session tokens securely”](#store-session-tokens-securely)
After successful identity verification using any of the auth methods (Magic Link & OTP, social, enterprise SSO), your application receives session tokens(access and refresh tokens) towards the [end of the login](/authenticate/fsa/complete-login/).
* 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
}
```
Request offline\_access to receive a refresh token
A refresh token is only included in the authentication response when you include the `offline_access` scope in your authorization URL. If your authorization URL does not include `offline_access`, `authResult.refreshToken` will be `null` or undefined.
Always include `offline_access` alongside `openid`, `profile`, and `email` when building your authorization URL:
```js
1
scopes: ['openid', 'profile', 'email', 'offline_access']
```
Additionally, Scalekit **rotates refresh tokens** — every time you use a refresh token to get a new access token, you receive a new refresh token. Store the new refresh token immediately and discard the old one. Replaying a used refresh token will result in an error.
Store each token based on its security requirements. For SPAs and mobile apps, consider storing access tokens in memory and sending via `Authorization: Bearer` headers to minimize CSRF exposure. For traditional web apps, use the cookie-based approach below:
* **Access Token**: Store in a secure, HttpOnly cookie with proper `Path` scoping (e.g., `/api`) to prevent XSS attacks. This token has a short lifespan and provides access to protected resources.
* **Refresh Token**: Store in a separate HttpOnly, Secure cookie with `Path=/auth/refresh` scoping. This limits the refresh token to only be sent to your refresh endpoint, reducing exposure. Rotate the token on each use to detect theft.
* **ID Token**: Ensure it is stored in local storage or a cookie so that it remains accessible at runtime, which is necessary for logging the user out successfully.
- Node.js
Express.js
```javascript
4 collapsed lines
1
import cookieParser from 'cookie-parser';
2
// Enable parsing of cookies from request headers
3
app.use(cookieParser());
4
5
// Extract authentication data from the successful authentication response
6
const { accessToken, expiresIn, refreshToken, user } = authResult;
7
8
// Encrypt tokens before storing to add an additional security layer
9
const encryptedAccessToken = encrypt(accessToken);
10
const encryptedRefreshToken = encrypt(refreshToken);
11
12
// Store encrypted access token in HttpOnly cookie
13
res.cookie('accessToken', encryptedAccessToken, {
14
maxAge: (expiresIn - 60) * 1000, // Subtract 60s buffer for clock skew (milliseconds)
15
httpOnly: true, // Prevents JavaScript access to mitigate XSS attacks
16
secure: process.env.NODE_ENV === 'production', // HTTPS-only in production
17
sameSite: 'strict' // Prevents CSRF attacks
18
});
19
20
// Store encrypted refresh token in separate HttpOnly cookie
21
res.cookie('refreshToken', encryptedRefreshToken, {
22
httpOnly: true, // Prevents JavaScript access to mitigate XSS attacks
23
secure: process.env.NODE_ENV === 'production', // HTTPS-only in production
24
sameSite: 'strict' // Prevents CSRF attacks
25
});
```
- Python
Flask
```python
4 collapsed lines
1
from flask import Flask, make_response, request
2
import os
3
app = Flask(__name__)
4
5
# Extract authentication data from the successful authentication response
6
access_token = auth_result.access_token
7
expires_in = auth_result.expires_in
8
refresh_token = auth_result.refresh_token
9
user = auth_result.user
10
11
# Encrypt tokens before storing to add an additional security layer
12
encrypted_access_token = encrypt(access_token)
13
encrypted_refresh_token = encrypt(refresh_token)
14
15
response = make_response()
16
17
# Store encrypted access token in HttpOnly cookie
18
response.set_cookie(
19
'accessToken',
20
encrypted_access_token,
21
max_age=expires_in - 60, # Subtract 60s buffer for clock skew (seconds in Flask)
22
httponly=True, # Prevents JavaScript access to mitigate XSS attacks
23
secure=os.environ.get('FLASK_ENV') == 'production', # HTTPS-only in production
24
samesite='Strict' # Prevents CSRF attacks
25
)
26
27
# Store encrypted refresh token in separate HttpOnly cookie
28
response.set_cookie(
29
'refreshToken',
30
encrypted_refresh_token,
31
httponly=True, # Prevents JavaScript access to mitigate XSS attacks
32
secure=os.environ.get('FLASK_ENV') == 'production', # HTTPS-only in production
33
samesite='Strict' # Prevents CSRF attacks
34
)
```
- Go
Gin
```go
7 collapsed lines
1
import (
2
"net/http"
3
"os"
4
"time"
5
"github.com/gin-gonic/gin"
6
)
7
8
// Extract authentication data from the successful authentication response
9
accessToken := authResult.AccessToken
10
expiresIn := authResult.ExpiresIn
11
refreshToken := authResult.RefreshToken
12
user := authResult.User
13
14
// Encrypt tokens before storing to add an additional security layer
15
encryptedAccessToken := encrypt(accessToken)
16
encryptedRefreshToken := encrypt(refreshToken)
17
18
// Set SameSite mode for CSRF protection
19
c.SetSameSite(http.SameSiteStrictMode) // Prevents CSRF attacks
20
21
// Store encrypted access token in HttpOnly cookie
22
c.SetCookie(
23
"accessToken",
24
encryptedAccessToken,
25
expiresIn-60, // Subtract 60s buffer for clock skew (seconds in Gin)
26
"/", // Available on all routes
27
"",
28
os.Getenv("GIN_MODE") == "release", // HTTPS-only in production
29
true, // Prevents JavaScript access to mitigate XSS attacks
30
)
31
32
// Store encrypted refresh token in separate HttpOnly cookie
33
c.SetCookie(
34
"refreshToken",
35
encryptedRefreshToken,
36
0, // No expiry for refresh token cookie (session lifetime controlled server-side)
37
"/", // Available on all routes
38
"",
39
os.Getenv("GIN_MODE") == "release", // HTTPS-only in production
40
true, // Prevents JavaScript access to mitigate XSS attacks
41
)
```
- Java
Spring
```java
6 collapsed lines
1
import javax.servlet.http.Cookie;
2
import javax.servlet.http.HttpServletResponse;
3
import org.springframework.core.env.Environment;
4
@Autowired
5
private Environment env;
6
7
// Extract authentication data from the successful authentication response
8
String accessToken = authResult.getAccessToken();
9
int expiresIn = authResult.getExpiresIn();
10
String refreshToken = authResult.getRefreshToken();
11
User user = authResult.getUser();
12
13
// Encrypt tokens before storing to add an additional security layer
14
String encryptedAccessToken = encrypt(accessToken);
15
String encryptedRefreshToken = encrypt(refreshToken);
16
17
// Store encrypted access token in HttpOnly cookie
18
Cookie accessTokenCookie = new Cookie("accessToken", encryptedAccessToken);
19
accessTokenCookie.setMaxAge(expiresIn - 60); // Subtract 60s buffer for clock skew (seconds in Spring)
20
accessTokenCookie.setHttpOnly(true); // Prevents JavaScript access to mitigate XSS attacks
21
accessTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0])); // HTTPS-only in production
22
accessTokenCookie.setPath("/"); // Available on all routes
23
response.addCookie(accessTokenCookie);
24
response.setHeader("Set-Cookie",
25
response.getHeader("Set-Cookie") + "; SameSite=Strict"); // Prevents CSRF attacks
26
27
// Store encrypted refresh token in separate HttpOnly cookie
28
Cookie refreshTokenCookie = new Cookie("refreshToken", encryptedRefreshToken);
29
refreshTokenCookie.setHttpOnly(true); // Prevents JavaScript access to mitigate XSS attacks
30
refreshTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0])); // HTTPS-only in production
31
refreshTokenCookie.setPath("/"); // Available on all routes
32
response.addCookie(refreshTokenCookie);
```
2. ## Check the access token before handling requests
[Section titled “Check the access token before handling requests”](#check-the-access-token-before-handling-requests)
Validate every request for a valid access token in your application. Create middleware to protect your application routes. This middleware validates the access token on every request to secured endpoints. For APIs, consider reading from `Authorization: Bearer` headers instead of cookies to minimize CSRF risk.
Here’s an example middleware method validating the access token and refreshing it if expired for every request.
* Node.js
middleware/auth.js
```javascript
1
async function verifyToken(req, res, next) {
2
// Extract encrypted tokens from request cookies
3
const { accessToken, refreshToken } = req.cookies;
4
5
if (!accessToken) {
6
return res.status(401).json({ error: 'Authentication required' });
7
}
8
9
try {
10
// Decrypt the access token before validation
11
const decryptedAccessToken = decrypt(accessToken);
12
13
// Verify token validity using Scalekit's validation method
14
const isValid = await scalekit.validateAccessToken(decryptedAccessToken);
15
16
if (!isValid && refreshToken) {
17
// Token expired - refresh it transparently
18
const decryptedRefreshToken = decrypt(refreshToken);
19
const authResult = await scalekit.refreshAccessToken(decryptedRefreshToken);
20
21
// Encrypt and store new tokens
22
res.cookie('accessToken', encrypt(authResult.accessToken), {
23
maxAge: (authResult.expiresIn - 60) * 1000,
24
httpOnly: true,
25
secure: process.env.NODE_ENV === 'production',
26
sameSite: 'strict'
27
});
28
29
res.cookie('refreshToken', encrypt(authResult.refreshToken), {
30
httpOnly: true,
31
secure: process.env.NODE_ENV === 'production',
32
sameSite: 'strict'
33
});
34
35
return next();
36
}
37
38
if (!isValid) {
39
return res.status(401).json({ error: 'Session expired. Please sign in again.' });
40
}
41
42
// Token is valid, proceed to the next middleware or route handler
43
next();
44
} catch (error) {
45
return res.status(401).json({ error: 'Authentication failed' });
46
}
47
}
```
* Python
middleware/auth.py
```python
2 collapsed lines
1
from flask import request, jsonify
2
from functools import wraps
3
def verify_token(f):
4
@wraps(f)
5
def decorated_function(*args, **kwargs):
6
# Extract encrypted tokens from request cookies
7
access_token = request.cookies.get('accessToken')
8
refresh_token = request.cookies.get('refreshToken')
9
10
if not access_token:
11
return jsonify({'error': 'Authentication required'}), 401
12
13
try:
14
# Decrypt the access token before validation
15
decrypted_access_token = decrypt(access_token)
16
17
# Verify token validity using Scalekit's validation method
18
is_valid = scalekit_client.validate_access_token(decrypted_access_token)
19
20
if not is_valid and refresh_token:
21
# Token expired - refresh it transparently
22
decrypted_refresh_token = decrypt(refresh_token)
23
auth_result = scalekit_client.refresh_access_token(decrypted_refresh_token)
24
25
# Encrypt and store new tokens
26
response = make_response(f(*args, **kwargs))
27
response.set_cookie(
28
'accessToken',
29
encrypt(auth_result.access_token),
30
max_age=auth_result.expires_in - 60,
31
httponly=True,
32
secure=os.environ.get('FLASK_ENV') == 'production',
33
samesite='Strict'
34
)
35
response.set_cookie(
36
'refreshToken',
37
encrypt(auth_result.refresh_token),
38
httponly=True,
39
secure=os.environ.get('FLASK_ENV') == 'production',
40
samesite='Strict'
41
)
42
return response
43
44
if not is_valid:
45
return jsonify({'error': 'Session expired. Please sign in again.'}), 401
46
47
# Token is valid, proceed to the protected view function
48
return f(*args, **kwargs)
49
50
except Exception:
51
return jsonify({'error': 'Authentication failed'}), 401
52
53
return decorated_function
```
* Go
middleware/auth.go
```go
5 collapsed lines
1
import (
2
"net/http"
3
"os"
4
"github.com/gin-gonic/gin"
5
)
6
func VerifyToken() gin.HandlerFunc {
7
return func(c *gin.Context) {
8
// Extract encrypted tokens from request cookies
9
accessToken, err := c.Cookie("accessToken")
10
if err != nil || accessToken == "" {
11
c.JSON(http.StatusUnauthorized, gin.H{"error": "Authentication required"})
12
c.Abort()
13
return
14
}
15
16
// Decrypt the access token before validation
17
decryptedAccessToken := decrypt(accessToken)
18
19
// Verify token validity using Scalekit's validation method
20
isValid, err := scalekitClient.ValidateAccessToken(c.Request.Context(), decryptedAccessToken)
21
22
if (err != nil || !isValid) {
23
// Token expired - attempt transparent refresh
24
refreshToken, err := c.Cookie("refreshToken")
25
if err == nil && refreshToken != "" {
26
decryptedRefreshToken := decrypt(refreshToken)
27
authResult, err := scalekitClient.RefreshAccessToken(c.Request.Context(), decryptedRefreshToken)
28
29
if err == nil {
30
// Encrypt and store new tokens
31
c.SetSameSite(http.SameSiteStrictMode)
32
c.SetCookie(
33
"accessToken",
34
encrypt(authResult.AccessToken),
35
authResult.ExpiresIn-60,
36
"/",
37
"",
38
os.Getenv("GIN_MODE") == "release",
39
true,
40
)
41
c.SetCookie(
42
"refreshToken",
43
encrypt(authResult.RefreshToken),
44
0,
45
"/",
46
"",
47
os.Getenv("GIN_MODE") == "release",
48
true,
49
)
50
c.Next()
51
return
52
}
53
}
54
55
c.JSON(http.StatusUnauthorized, gin.H{"error": "Session expired. Please sign in again."})
56
c.Abort()
57
return
58
}
59
60
// Token is valid, proceed to the next handler in the chain
61
c.Next()
62
}
63
}
```
* Java
middleware/AuthInterceptor.java
```java
5 collapsed lines
1
import javax.servlet.http.HttpServletRequest;
2
import javax.servlet.http.HttpServletResponse;
3
import javax.servlet.http.Cookie;
4
import org.springframework.web.servlet.HandlerInterceptor;
5
import org.springframework.core.env.Environment;
6
7
/**
8
* Intercepts HTTP requests to verify authentication tokens.
9
* Transparently refreshes expired tokens to maintain user sessions.
10
*/
11
@Component
12
public class AuthInterceptor implements HandlerInterceptor {
13
@Autowired
14
private Environment env;
15
16
@Override
17
public boolean preHandle(
18
HttpServletRequest request,
19
HttpServletResponse response,
20
Object handler
21
) throws Exception {
7 collapsed lines
22
// Extract encrypted tokens from cookies
23
String accessToken = getCookieValue(request, "accessToken");
24
String refreshToken = getCookieValue(request, "refreshToken");
25
26
if (accessToken == null) {
27
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
28
response.getWriter().write("{\"error\": \"Authentication required\"}");
29
return false;
30
}
31
32
try {
33
// Decrypt the access token before validation
34
String decryptedAccessToken = decrypt(accessToken);
35
36
// Verify token validity using Scalekit's validation method
37
boolean isValid = scalekitClient.validateAccessToken(decryptedAccessToken);
38
39
if (!isValid && refreshToken != null) {
40
// Token expired - refresh it transparently
41
String decryptedRefreshToken = decrypt(refreshToken);
42
AuthResult authResult = scalekitClient.authentication().refreshToken(decryptedRefreshToken);
43
44
// Encrypt and store new tokens
20 collapsed lines
45
Cookie accessTokenCookie = new Cookie("accessToken", encrypt(authResult.getAccessToken()));
46
accessTokenCookie.setMaxAge(authResult.getExpiresIn() - 60);
47
accessTokenCookie.setHttpOnly(true);
48
accessTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0]));
49
accessTokenCookie.setPath("/");
50
response.addCookie(accessTokenCookie);
51
52
Cookie refreshTokenCookie = new Cookie("refreshToken", encrypt(authResult.getRefreshToken()));
53
refreshTokenCookie.setHttpOnly(true);
54
refreshTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0]));
55
refreshTokenCookie.setPath("/");
56
response.addCookie(refreshTokenCookie);
57
response.setHeader("Set-Cookie", response.getHeader("Set-Cookie") + "; SameSite=Strict");
58
59
return true;
60
}
61
62
if (!isValid) {
63
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
64
response.getWriter().write("{\"error\": \"Session expired. Please sign in again.\"}");
65
return false;
66
}
67
68
// Token is valid, allow request to proceed
69
return true;
70
} catch (Exception e) {
71
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
72
response.getWriter().write("{\"error\": \"Authentication failed\"}");
73
return false;
74
}
75
}
76
77
private String getCookieValue(HttpServletRequest request, String cookieName) {
78
Cookie[] cookies = request.getCookies();
79
if (cookies != null) {
80
for (Cookie cookie : cookies) {
81
if (cookieName.equals(cookie.getName())) {
82
return cookie.getValue();
83
}
84
}
85
}
86
return null;
87
}
88
}
```
TypeScript: get typed claims from validateToken
Use a generic type parameter to get properly typed claims instead of `unknown`. Pass `JWTPayload` from `jose` for access tokens, or `IdTokenClaim` from `@scalekit-sdk/node` for ID tokens:
```typescript
1
import type { JWTPayload } from 'jose';
2
import type { IdTokenClaim } from '@scalekit-sdk/node';
3
4
// Access token — typed as JWTPayload
5
const claims = await scalekit.validateToken(accessToken);
6
console.log(claims.sub); // user ID
7
8
// ID token — typed with full user profile claims
9
const idClaims = await scalekit.validateToken(idToken);
10
console.log(idClaims.email);
```
3. ## Configure session security and duration
[Section titled “Configure session security and duration”](#configure-session-security-and-duration)
Manage user session behavior directly from your Scalekit dashboard without modifying application code. Configure session durations and authentication frequency to balance security and user experience for your application.
In your Scalekit dashboard, the **Session settings** page lets you set these options:
* **Absolute session timeout**: This is the maximum time a user can stay signed in, no matter what. After this time, they must log in again. For example, if you set it to 30 minutes, users will be logged out after 30 minutes, even if they are still using your app.
* **Idle session timeout**: This is the time your app waits before logging out a user who is not active. If you turn this on, the session will end if the user does nothing for the set time. For example, if you set it to 10 minutes, and the user does not click or type for 10 minutes, they will be logged out.
* **Access token lifetime**: This is how long an access token is valid. When it expires, your app needs to get a new token (using the refresh token) so the user can keep using the app without logging in again. For example, if you set it to 5 minutes, your app will need to refresh the token every 5 minutes.
Shorter timeouts provide better security, while longer timeouts reduce authentication interruptions.
4. ## Manage sessions remotely API
[Section titled “Manage sessions remotely ”](#manage-sessions-remotely)
Beyond client-side session management, Scalekit provides powerful APIs to manage user sessions remotely from your backend application. This enables you to build features like active session management in user account settings, security incident response, or administrative session control.
These APIs are particularly useful for:
* Displaying all active sessions in user account settings
* Allowing users to revoke specific sessions from unfamiliar devices
* Security incident response and suspicious session termination
- Node.js
Session Management SDK
```javascript
1
// Get details for a specific session
2
const sessionDetails = await scalekit.session.getSession('ses_1234567890123456');
3
4
// List all sessions for a user with optional filtering
5
const userSessions = await scalekit.session.getUserSessions('usr_1234567890123456', {
6
pageSize: 10,
7
filter: {
8
status: ['ACTIVE'], // Filter for active sessions only
9
startTime: new Date('2025-01-01T00:00:00Z'),
10
endTime: new Date('2025-12-31T23:59:59Z')
11
}
12
});
13
14
// Revoke a specific session (useful for "Sign out this device" functionality)
15
const revokedSession = await scalekit.session.revokeSession('ses_1234567890123456');
16
17
// Revoke all sessions for a user (useful for "Sign out all devices" functionality)
18
const revokedSessions = await scalekit.session.revokeAllUserSessions('usr_1234567890123456');
19
console.log(`Revoked sessions for user`);
```
- Python
Session Management SDK
```python
1
# Get details for a specific session
2
session_details = scalekit_client.session.get_session(session_id="ses_1234567890123456")
3
4
# List all sessions for a user with optional filtering
5
from google.protobuf.timestamp_pb2 import Timestamp
6
from datetime import datetime
7
8
start_time = Timestamp()
9
start_time.FromDatetime(datetime(2025, 1, 1))
10
end_time = Timestamp()
11
end_time.FromDatetime(datetime(2025, 12, 31))
12
13
filter_obj = scalekit_client.session.create_session_filter(
14
status=["ACTIVE"], start_time=start_time, end_time=end_time
15
)
16
user_sessions = scalekit_client.session.get_user_sessions(
17
user_id="usr_1234567890123456", page_size=10, filter=filter_obj
18
)
19
20
# Revoke a specific session (useful for "Sign out this device" functionality)
21
revoked_session = scalekit_client.session.revoke_session(session_id="ses_1234567890123456")
22
23
# Revoke all sessions for a user (useful for "Sign out all devices" functionality)
24
revoked_sessions = scalekit_client.session.revoke_all_user_sessions(user_id="usr_1234567890123456")
25
print(f"Revoked sessions for user")
```
- Go
Session Management SDK
```go
1
// Get details for a specific session
2
sessionDetails, err := scalekitClient.Session().GetSession(ctx, "ses_1234567890123456")
3
if err != nil {
4
log.Fatal(err)
5
}
6
7
// List all sessions for a user with optional filtering
8
// import "time", sessionsv1 "...", "google.golang.org/protobuf/types/known/timestamppb"
9
startTime, _ := time.Parse(time.RFC3339, "2025-01-01T00:00:00Z")
10
endTime, _ := time.Parse(time.RFC3339, "2025-12-31T23:59:59Z")
11
filter := &sessionsv1.UserSessionFilter{
12
Status: []string{"ACTIVE"}, // Filter for active sessions only
13
StartTime: timestamppb.New(startTime),
14
EndTime: timestamppb.New(endTime),
15
}
16
userSessions, err := scalekitClient.Session().GetUserSessions(ctx, "usr_1234567890123456", 10, "", filter)
17
if err != nil {
18
log.Fatal(err)
19
}
20
21
// Revoke a specific session (useful for "Sign out this device" functionality)
22
revokedSession, err := scalekitClient.Session().RevokeSession(ctx, "ses_1234567890123456")
23
if err != nil {
24
log.Fatal(err)
25
}
26
27
// Revoke all sessions for a user (useful for "Sign out all devices" functionality)
28
revokedSessions, err := scalekitClient.Session().RevokeAllUserSessions(ctx, "usr_1234567890123456")
29
if err != nil {
30
log.Fatal(err)
31
}
32
fmt.Printf("Revoked sessions for user")
```
- Java
Session Management SDK
```java
1
// Get details for a specific session
2
SessionDetails sessionDetails = scalekitClient.sessions().getSession("ses_1234567890123456");
3
4
// List all sessions for a user with optional filtering
5
// import UserSessionFilter, Timestamp, Instant
6
UserSessionFilter filter = UserSessionFilter.newBuilder()
7
.addStatus("ACTIVE")
8
.setStartTime(Timestamp.newBuilder().setSeconds(Instant.parse("2025-01-01T00:00:00Z").getEpochSecond()).build())
9
.setEndTime(Timestamp.newBuilder().setSeconds(Instant.parse("2025-12-31T23:59:59Z").getEpochSecond()).build())
10
.build();
11
UserSessionDetails userSessions = scalekitClient.sessions().getUserSessions("usr_1234567890123456", 10, "", filter);
12
13
// Revoke a specific session (useful for "Sign out this device" functionality)
14
RevokeSessionResponse revokedSession = scalekitClient.sessions().revokeSession("ses_1234567890123456");
15
16
// Revoke all sessions for a user (useful for "Sign out all devices" functionality)
17
RevokeAllUserSessionsResponse revokedSessions = scalekitClient.sessions().revokeAllUserSessions("usr_1234567890123456");
18
System.out.println("Revoked sessions for user");
```
Your application continuously validates the access token for each incoming request. When the token is valid, the user’s session remains active. If the access token expires, your middleware transparently refreshes it using the stored refresh token—users never notice this happening. If the refresh token itself expires or becomes invalid, users are prompted to sign in again.
---
# DOCUMENT BOUNDARY
---
# Manage applications
> Register and manage applications in your shared authentication system
Register and manage applications in Scalekit. Each application gets its own OAuth client and configuration while sharing the same underlying user session across your web, mobile, and desktop apps.
1. ## Navigate to Applications
[Section titled “Navigate to Applications”](#navigate-to-applications)
1. Sign in to ****
2. From the left sidebar, go to **Developers > Applications**
You will see a list of applications already created for the selected environment.
Scalekit creates a default web application
Scalekit creates a **default web application** for every environment at creation time to help developers get started quickly. This app is environment-scoped and **cannot be deleted**.
2. ## Create a new application
[Section titled “Create a new application”](#create-a-new-application)
Click **Create Application** to add a new app. You’ll be asked to provide:
* **Application name** — A human-readable name for identifying the app
* **Application type** — Determines how authentication and credentials work
Available application types:
* **Web Application** — Server-side applications that can securely store secrets
* **Single Page Application (SPA)** — Browser-based applications; public clients with PKCE enforced
* **Native Application** — Desktop or mobile apps; public clients with PKCE enforced
Once created, Scalekit generates a **Client ID**. Only Web Applications can generate **Client Secrets**.
3. ## Application configuration
[Section titled “Application configuration”](#application-configuration)
### Application details
[Section titled “Application details”](#application-details)
Open an application to view and edit its configuration.
* **Allow Scalekit Management API access** — Enables this application’s credentials to call Scalekit Management APIs. Applicable only to **Web Applications**.
* **Enforce PKCE** — Requires PKCE for authorization requests. Always enabled and not editable for **SPA** and **Native** applications.
* **Access token expiry time** — Overrides the environment default access token lifetime for this application.
Access token expiry must be shorter than idle session timeout
If tokens outlive the session, users may encounter inconsistent logout behavior across apps. When the session expires but the access token is still valid, subsequent token refresh attempts will fail because the underlying session no longer exists.
### Client credentials
[Section titled “Client credentials”](#client-credentials)
Each application has a unique **Client ID**. When you generate a new client secret, Scalekit shows it **only once**. Copy and store it securely.
Treat client secrets like passwords
Anyone with access to your client secret can authenticate as your application and obtain tokens for any user. Never commit secrets to version control, expose them in client-side code, or share them in plain text. Use environment variables or a secrets manager.
* **Web Applications**
* Can generate a **Client Secret**
* A maximum of **two active secrets** is allowed at a time
* Generating a new secret always creates a **new value**, enabling safe rotation
* **SPA and Native Applications**
* Do not have client secrets
* Authenticate using Authorization Code with PKCE only
4. ## Configure redirect URLs
[Section titled “Configure redirect URLs”](#configure-redirect-urls)
Open the **Redirects** tab for an application to manage redirect endpoints. These URLs act as an allowlist and control where Scalekit can redirect users during authentication flows.
### Redirect URL types
[Section titled “Redirect URL types”](#redirect-url-types)
* **Post login URLs** — Allowed values for `redirect_uri` used with `/oauth/authorize`
* **Initiate login URL** — Where Scalekit redirects users when authentication starts outside your app
* **Post logout URLs** — Where users are redirected after a successful logout
* **Back-channel logout URL** — A secure endpoint that Scalekit calls to notify your application that a user session has been revoked
Back-channel logout is only available for Web Applications
Back-channel logout requires a backend endpoint to receive notifications from Scalekit. SPA and Native applications cannot receive back-channel logout notifications because they don’t have a persistent server.
For definitions, validation rules, custom URI schemes, and environment-specific behavior, see [Redirect URL configuration](/guides/dashboard/redirects/).
5. ## Delete an application
[Section titled “Delete an application”](#delete-an-application)
Delete applications from the bottom of the configuration page.
Deleting an application is permanent
This action is **permanent and irreversible**. Existing refresh tokens associated with the application will no longer be valid, and users will need to re-authenticate. Ensure you have communicated this change to affected users before deleting.
---
# DOCUMENT BOUNDARY
---
# Mobile & desktop applications
> Implement Multi-App Authentication for mobile and desktop apps using Authorization Code with PKCE
Implement login, token management, and logout in your mobile or desktop application using Authorization Code with PKCE. Native apps are public OAuth clients that cannot securely store a `client_secret` in the application binary, so they use PKCE to protect the authorization flow. This guide covers initiating login through the system browser, handling deep link callbacks, managing tokens in secure storage, and implementing logout.
Tip
[**Check out the example apps on GitHub**](https://github.com/scalekit-inc/multiapp-demo) to see Web, SPA, Desktop, and Mobile apps sharing a single Scalekit session.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before you begin, ensure you have:
* A Scalekit account with an environment configured
* Your environment URL (`ENV_URL`), e.g., `https://yourenv.scalekit.com`
* A native application registered in Scalekit with a `client_id` ([Create one](/authenticate/fsa/multiapp/manage-apps))
* A callback URI configured:
* **Mobile**: Custom URI scheme (e.g., `myapp://callback`) or universal/app links
* **Desktop**: Custom URI scheme or loopback address (e.g., `http://127.0.0.1:PORT/callback`)
## High-level flow
[Section titled “High-level flow”](#high-level-flow)
## Step-by-step implementation
[Section titled “Step-by-step implementation”](#step-by-step-implementation)
1. ## Initiate login or signup
[Section titled “Initiate login or signup”](#initiate-login-or-signup)
Initiate login by opening the system browser with the authorization URL. Always use the system browser rather than an embedded WebView — this lets users leverage existing sessions and provides a familiar, secure authentication experience.
```sh
1
/oauth/authorize?
2
response_type=code&
3
client_id=&
4
redirect_uri=&
5
scope=openid+profile+email+offline_access&
6
state=&
7
code_challenge=&
8
code_challenge_method=S256
```
Generate and store these values before opening the browser:
* `state` — Validate this on callback to prevent CSRF attacks
* `code_verifier` — A cryptographically random string you keep in the app
* `code_challenge` — Derived from the verifier using S256 hashing; send this in the authorization URL
Why PKCE is required for native apps
Native apps cannot keep a `client_secret` secure because the secret would be embedded in the application binary and could be extracted through reverse engineering. PKCE protects against authorization code interception attacks where malware on the device captures the authorization code from the callback URI.
For detailed parameter definitions, see [Initiate signup/login](/authenticate/fsa/implement-login).
2. ## Handle the callback and complete login
[Section titled “Handle the callback and complete login”](#handle-the-callback-and-complete-login)
After authentication, Scalekit redirects the user back to your application using the registered callback mechanism.
Common callback patterns:
* **Mobile apps** — Custom URI schemes (e.g., `myapp://callback`) or universal links (iOS) / app links (Android)
* **Desktop apps** — Custom URI schemes or a temporary HTTP server on localhost
Your callback handler must:
* Validate the returned `state` matches what you stored — this confirms the response is for your original request
* Handle any error parameters before processing
* Exchange the authorization code for tokens by including the `code_verifier`
```sh
1
POST /oauth/token
2
Content-Type: application/x-www-form-urlencoded
3
4
grant_type=authorization_code&
5
client_id=&
6
code=&
7
redirect_uri=&
8
code_verifier=
```
```json
1
{
2
"access_token": "...",
3
"refresh_token": "...",
4
"id_token": "...",
5
"expires_in": 299
6
}
```
Authorization codes expire after one use
Authorization codes are single-use and expire quickly (approximately 10 minutes). If you attempt to reuse a code or it expires, start a new login flow to obtain a fresh authorization code.
3. ## Manage sessions and token refresh
[Section titled “Manage sessions and token refresh”](#manage-sessions-and-token-refresh)
Store tokens in platform-specific secure storage and validate them on each request. When access tokens expire, use the refresh token to obtain new ones without requiring the user to re-authenticate.
**Token roles**
* **Access token** — Short-lived token (default 5 minutes) for authenticated API requests
* **Refresh token** — Long-lived token to obtain new access tokens
* **ID token** — JWT containing user identity claims; required for logout
Store tokens using secure, OS-backed storage appropriate for each platform. See [Token storage security](#token-storage-security) for platform-specific recommendations.
When an access token expires, request new tokens:
```sh
1
POST /oauth/token
2
Content-Type: application/x-www-form-urlencoded
3
4
grant_type=refresh_token&
5
client_id=&
6
refresh_token=
```
Validate access tokens by verifying:
* Token signature using Scalekit’s public keys (JWKS endpoint)
* `iss` matches your Scalekit environment URL
* `aud` includes your `client_id`
* `exp` and `iat` are valid timestamps
Public keys for signature verification:
```sh
1
/keys
```
4. ## Implement logout
[Section titled “Implement logout”](#implement-logout)
Clear your local session and redirect the system browser to Scalekit’s logout endpoint to invalidate the shared session.
Your logout action must:
* Extract the ID token before clearing local storage
* Clear tokens from secure storage
* Open the system browser to Scalekit’s logout endpoint
```sh
1
/oidc/logout?
2
id_token_hint=&
3
post_logout_redirect_uri=
```
Logout must open the system browser
Use the system browser to navigate to the `/oidc/logout` endpoint, not a backend API call. The browser ensures Scalekit’s session cookie is sent with the request, allowing Scalekit to identify and terminate the correct session.
## Handle errors
[Section titled “Handle errors”](#handle-errors)
When authentication fails, Scalekit redirects to your callback URI with error parameters instead of an authorization code:
```plaintext
1
myapp://callback?error=access_denied&error_description=User+denied+access&state=
```
Check for errors before processing the authorization code:
* Check if the `error` parameter exists in the callback URI
* Log the `error` and `error_description` for debugging
* Display a user-friendly message in your app
* Provide an option to retry login
Common error codes:
| Error | Description |
| ----------------- | ------------------------------------------------------------ |
| `access_denied` | User denied the authorization request |
| `invalid_request` | Missing or invalid parameters (e.g., invalid PKCE challenge) |
| `server_error` | Scalekit encountered an unexpected error |
## Token storage security
[Section titled “Token storage security”](#token-storage-security)
Native apps have access to platform-specific secure storage mechanisms that encrypt tokens at rest and protect them from other applications. Unlike browser storage, these mechanisms provide strong protection against token theft from device compromise or malware.
Use platform-specific secure storage for each platform:
| Platform | Recommended Storage |
| -------- | -------------------------------------- |
| iOS | Keychain Services |
| Android | EncryptedSharedPreferences or Keystore |
| macOS | Keychain |
| Windows | Windows Credential Manager or DPAPI |
| Linux | Secret Service API (libsecret) |
**Recommendations:**
* Never store tokens in plain text files, shared preferences, or unencrypted databases — these can be read by any application with storage access
* Use biometric or device PIN protection for sensitive token access when available — this adds a second factor for token access
* Clear tokens from secure storage on logout — this ensures a clean state for the next authentication
Never embed secrets in your application binary
Credentials embedded in application code or configuration files can be extracted through reverse engineering. Always use PKCE for native apps instead of relying on a `client_secret`. If you need to make authenticated API calls from your backend, use a separate web application with proper secret management.
## What’s next
[Section titled “What’s next”](#whats-next)
* [Set up a custom domain](/guides/custom-domain) for your authentication pages
* [Add enterprise SSO](/authenticate/auth-methods/enterprise-sso/) to support SAML and OIDC with your customers’ identity providers
---
# DOCUMENT BOUNDARY
---
# Multi-App Authentication
> Share authentication across web, mobile, and desktop applications with a unified session
Register multiple applications as OAuth clients that share a single Scalekit user session. Users authenticate once and gain access everywhere across your web app, mobile app, desktop client, and documentation site. Each application gets its own OAuth client with appropriate credentials based on its type, while all apps share the same underlying session.
[Check out the example apps ](https://github.com/scalekit-inc/multiapp-demo)
Use multi-app authentication when you ship multiple apps (web, mobile, desktop, or SPA), users expect to stay signed in across surfaces, or you need centralized session control and auditability. Each app gets its own OAuth client for clearer audit logs, safer scope boundaries, and easier maintenance. This eliminates friction from repeated logins and closes security gaps from inconsistent session handling.
## How multi-app authentication works
[Section titled “How multi-app authentication works”](#how-multi-app-authentication-works)
1. [Register](/authenticate/fsa/multiapp/manage-apps/) each application as an OAuth client in Scalekit.
2. User logs into any app.
3. Scalekit creates a session for that user.
4. Other apps detect the session and skip the login prompt.
5. Logging out of any app terminates the shared session.
Each app must clear its own local state
Revoking the Scalekit session does not automatically clear your application’s local state. Each app must clear its own session and stored tokens. A failed **refresh token exchange** is a reliable signal that the shared session has been revoked. For proactive sign-out across all applications, configure [back-channel logout URLs](/authenticate/fsa/multiapp/manage-apps/#configure-redirect-urls) so Scalekit can notify each app when the shared session is terminated.
## Application types and authentication flows
[Section titled “Application types and authentication flows”](#application-types-and-authentication-flows)
Each application is registered separately in Scalekit and receives its own OAuth client. Choose the application type based on whether it has a backend server that can securely store credentials:
| App Type | Description | Has Backend? | Uses Secret? | Auth Flow |
| --------------------------------------------------------------------------- | ----------------------------------------------------------- | :----------: | :----------: | ------------------ |
| [**Web app** (Express, Django, Rails)](/authenticate/fsa/multiapp/web-app) | Server-rendered or backend-driven apps with secure secrets. | ✓ | ✓ | Authorization Code |
| [**SPA** (React, Vue, Angular)](/authenticate/fsa/multiapp/single-page-app) | Frontend-only apps running fully in the browser. | ✗ | ✗ | Auth Code + PKCE |
| [**Mobile** (iOS, Android)](/authenticate/fsa/multiapp/native-app) | iOS or Android apps using system browser flows. | ✗ | ✗ | Auth Code + PKCE |
| [**Desktop** (Electron, Tauri)](/authenticate/fsa/multiapp/native-app) | Electron or native desktop apps with deep links. | ✗ | ✗ | Auth Code + PKCE |
Even though each app has a different `client_id`, they all rely on the same Scalekit user session. Separate clients per app give you clearer audit logs, safer scope boundaries, and easier long-term maintenance.
## Implementation steps
[Section titled “Implementation steps”](#implementation-steps)
1. **Create applications in Scalekit** — [Create applications](/authenticate/fsa/multiapp/manage-apps) in Scalekit for each of your apps. During setup, select the app type based on whether it has a backend and needs client secrets.
2. **Configure redirect URLs for each app** — Redirects are registered endpoints in Scalekit that control where users are sent during authentication flows. [Configure redirect URLs](/authenticate/fsa/multiapp/manage-apps/#configure-redirect-urls) for each application.
3. **Implement login flow for each app** — Once your applications are registered, each app follows an OAuth-based authentication flow. Use the [login implementation guide](/authenticate/fsa/implement-login/) for implementing login/signup flow in your apps.
4. **Manage sessions and token refresh** — After users successfully authenticate in any of your apps, you receive session tokens that manage their access. Use the [session management guide](/authenticate/fsa/manage-session/) to manage sessions in your apps.
Validate access tokens on each request
Validate access tokens by checking the issuer, audience (which must include the application’s `client_id`), `iat`, and `exp`. Store tokens securely, and use the `/oauth/token` endpoint with the `refresh_token` grant to obtain new access, refresh, and ID tokens when needed.
5. **Implement logout** — Initiate logout by calling the `/oidc/logout` endpoint with the relevant parameters. Clear your local application session when refresh token exchange fails, or configure back-channel logout to proactively sign users out across all applications sharing the same session. Follow the [logout implementation guide](/authenticate/fsa/logout/) to implement logout in your apps.
## Troubleshooting
[Section titled “Troubleshooting”](#troubleshooting)
Why am I getting a redirect URI mismatch error?
The exact URI (including trailing slashes and query parameters) must match what’s configured in **Dashboard > Developers > Applications > \[Your App] > Redirects**. Common mismatches include:
* `http` vs `https`
* Missing or extra trailing slash
* Different port numbers in development
Why aren’t my apps sharing authentication state?
Verify all applications are registered in the same Scalekit environment. Apps in different environments maintain separate session pools and cannot share authentication state.
Why are users prompted to login on every app?
Check the following:
* All apps use the same Scalekit environment URL
* The browser allows third-party cookies (required for session detection)
* The user is using the same browser across apps
Why is the refresh token being rejected?
The Scalekit session may have been revoked from another application, or the refresh token has expired. Redirect the user to log in again to establish a new session.
---
# DOCUMENT BOUNDARY
---
# Single page application
> Implement Multi-App Authentication for single page apps using Authorization Code with PKCE
Implement login, token management, and logout in your single page application (SPA) using Authorization Code with PKCE. SPAs run entirely in the browser and cannot securely store a `client_secret`, so they use PKCE (Proof Key for Code Exchange) to protect the authorization flow. This guide covers initiating login from your SPA, exchanging authorization codes for tokens, managing sessions, and implementing logout.
Tip
[**Check out the example apps on GitHub**](https://github.com/scalekit-inc/multiapp-demo) to see Web, SPA, Desktop, and Mobile apps sharing a single Scalekit session.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before you begin, ensure you have:
* A Scalekit account with an environment configured
* Your environment URL (`ENV_URL`), e.g., `https://yourenv.scalekit.com`
* A SPA registered in Scalekit with a `client_id` ([Create one](/authenticate/fsa/multiapp/manage-apps))
* At least one redirect URL configured in **Dashboard > Developers > Applications > \[Your App] > Redirects**
## High-level flow
[Section titled “High-level flow”](#high-level-flow)
## Step-by-step implementation
[Section titled “Step-by-step implementation”](#step-by-step-implementation)
1. ## Initiate login or signup
[Section titled “Initiate login or signup”](#initiate-login-or-signup)
Initiate login by redirecting the user to Scalekit’s hosted login page. Include the PKCE code challenge in the authorization request to protect against authorization code interception attacks.
```sh
1
/oauth/authorize?
2
response_type=code&
3
client_id=&
4
redirect_uri=&
5
scope=openid+profile+email+offline_access&
6
state=&
7
code_challenge=&
8
code_challenge_method=S256
```
Generate and store these values before redirecting:
* `state` — Validate this on callback to prevent CSRF attacks
* `code_verifier` — A cryptographically random string you keep locally
* `code_challenge` — Derived from the verifier using S256 hashing; send this in the authorization URL
Why PKCE is required for SPAs
SPAs are public clients that cannot keep a `client_secret` secure because all code runs in the browser. PKCE protects against authorization code interception attacks where an attacker captures the authorization code from the redirect URI. Without PKCE, anyone who intercepts the code could exchange it for tokens.
For detailed parameter definitions, see [Initiate signup/login](/authenticate/fsa/implement-login).
2. ## Handle the callback and complete login
[Section titled “Handle the callback and complete login”](#handle-the-callback-and-complete-login)
After authentication, Scalekit redirects the user back to your callback URL with an authorization `code` and the `state` you sent.
Your callback handler must:
* Validate the returned `state` matches what you stored — this confirms the response is for your original request
* Handle any error parameters before processing
* Exchange the authorization code for tokens by including the `code_verifier`
```sh
1
POST /oauth/token
2
Content-Type: application/x-www-form-urlencoded
3
4
grant_type=authorization_code&
5
client_id=&
6
code=&
7
redirect_uri=&
8
code_verifier=
```
```json
1
{
2
"access_token": "...",
3
"refresh_token": "...",
4
"id_token": "...",
5
"expires_in": 299
6
}
```
Authorization codes expire after one use
Authorization codes are single-use and expire quickly (approximately 10 minutes). If you attempt to reuse a code or it expires, start a new login flow to obtain a fresh authorization code.
3. ## Manage sessions and token refresh
[Section titled “Manage sessions and token refresh”](#manage-sessions-and-token-refresh)
Store tokens and validate them on each request. When access tokens expire, use the refresh token to obtain new ones without requiring the user to authenticate again.
**Token roles**
* **Access token** — Short-lived token (default 5 minutes) for authenticated API requests
* **Refresh token** — Long-lived token to obtain new access tokens
* **ID token** — JWT containing user identity claims; required for logout
Store tokens client-side based on your security requirements. See [Token storage security](#token-storage-security) for guidance on choosing the right storage mechanism.
When an access token expires, request new tokens:
```sh
1
POST /oauth/token
2
Content-Type: application/x-www-form-urlencoded
3
4
grant_type=refresh_token&
5
client_id=&
6
refresh_token=
```
Validate access tokens by verifying:
* Token signature using Scalekit’s public keys (JWKS endpoint)
* `iss` matches your Scalekit environment URL
* `aud` includes your `client_id`
* `exp` and `iat` are valid timestamps
Public keys for signature verification:
```sh
1
/keys
```
4. ## Implement logout
[Section titled “Implement logout”](#implement-logout)
Clear your local session and redirect to Scalekit’s logout endpoint to invalidate the shared session.
Your logout action must:
* Extract the ID token before clearing local storage
* Clear locally stored tokens from memory or storage
* Redirect the browser to Scalekit’s logout endpoint
```sh
1
/oidc/logout?
2
id_token_hint=&
3
post_logout_redirect_uri=
```
Logout must be a browser redirect
Use a browser redirect to the `/oidc/logout` endpoint, not an API call. The redirect ensures Scalekit’s session cookie is sent with the request, allowing Scalekit to identify and terminate the correct session. API calls from JavaScript do not include the session cookie.
## Handle errors
[Section titled “Handle errors”](#handle-errors)
When authentication fails, Scalekit redirects to your callback URL with error parameters instead of an authorization code:
```sh
/callback?error=access_denied&error_description=User+denied+access&state=
```
Check for errors before processing the authorization code:
* Check if the `error` parameter exists in the URL
* Log the `error` and `error_description` for debugging
* Display a user-friendly message
* Provide an option to retry login
Common error codes:
| Error | Description |
| ----------------- | ------------------------------------------------------------ |
| `access_denied` | User denied the authorization request |
| `invalid_request` | Missing or invalid parameters (e.g., invalid PKCE challenge) |
| `server_error` | Scalekit encountered an unexpected error |
## Token storage security
[Section titled “Token storage security”](#token-storage-security)
SPAs run entirely in the browser where tokens are vulnerable to cross-site scripting (XSS) attacks. An attacker who successfully injects malicious JavaScript can read tokens from any accessible storage and use them to impersonate the user.
Choose a storage strategy based on your security requirements:
| Storage | Security | Trade-off |
| ---------------------------- | --------------------------------------- | ---------------------------------------------------- |
| Memory (JavaScript variable) | Most secure — not accessible to XSS | Tokens lost on page refresh; requires silent refresh |
| Session storage | Moderate — cleared when tab closes | Accessible to XSS; persists during session |
| Local storage | Least secure — persists across sessions | Accessible to XSS; long exposure window |
**Recommendations:**
* For high-security applications, store tokens in memory and use silent refresh (iframe-based token renewal) to maintain sessions across page loads
* Always sanitize user inputs and use Content Security Policy (CSP) headers to mitigate XSS attacks
* Never log tokens or include them in error messages
Never store tokens in local storage for sensitive applications
Local storage is accessible to any JavaScript running on your page. If an attacker exploits an XSS vulnerability, they can read all tokens from local storage and fully compromise user accounts. For applications handling sensitive data, prefer memory storage with silent refresh.
## What’s next
[Section titled “What’s next”](#whats-next)
* [Set up a custom domain](/guides/custom-domain) for your authentication pages
* [Add enterprise SSO](/authenticate/auth-methods/enterprise-sso/) to support SAML and OIDC with your customers’ identity providers
---
# DOCUMENT BOUNDARY
---
# Web application
> Implement Multi-App Authentication for web apps using Authorization Code flow with client_id and client_secret
Implement login, token management, and logout in your web application using the Authorization Code flow. Web applications have a backend server that can securely store a `client_secret`, allowing them to authenticate directly with Scalekit’s token endpoint. This guide covers initiating login from your backend, exchanging authorization codes for tokens, managing sessions with secure cookies, and implementing logout.
Tip
[**Check out the example apps on GitHub**](https://github.com/scalekit-inc/multiapp-demo) to see Web, SPA, Desktop, and Mobile apps sharing a single Scalekit session.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before you begin, ensure you have:
* A Scalekit account with an environment configured
* Your environment URL (`ENV_URL`), e.g., `https://yourenv.scalekit.com`
* A web application registered in Scalekit with `client_id` and `client_secret` ([Create one](/authenticate/fsa/multiapp/manage-apps))
* At least one redirect URL configured in **Dashboard > Developers > Applications > \[Your App] > Redirects**
## High-level flow
[Section titled “High-level flow”](#high-level-flow)
## Step-by-step implementation
[Section titled “Step-by-step implementation”](#step-by-step-implementation)
1. ## Initiate login or signup
[Section titled “Initiate login or signup”](#initiate-login-or-signup)
Initiate login by redirecting the user to Scalekit’s hosted login page from your backend. Generate and store a `state` parameter before redirecting to validate the callback.
```sh
1
/oauth/authorize?
2
response_type=code&
3
client_id=&
4
redirect_uri=&
5
scope=openid+profile+email+offline_access&
6
state=
```
Why web apps use client\_secret
Web applications store the `client_secret` on the backend server where it cannot be accessed by browsers or end users. This allows your backend to authenticate directly with Scalekit’s token endpoint without needing PKCE. Never expose the `client_secret` to the frontend or include it in client-side JavaScript.
For detailed parameter definitions, see [Initiate signup/login](/authenticate/fsa/implement-login).
2. ## Handle the callback and complete login
[Section titled “Handle the callback and complete login”](#handle-the-callback-and-complete-login)
After authentication, Scalekit redirects the user back to your callback endpoint with an authorization `code` and the `state` you sent.
Your backend must:
* Validate the returned `state` matches what you stored — this confirms the response is for your original request and prevents CSRF attacks
* Handle any error parameters before processing
* Exchange the authorization code for tokens using your `client_secret`
```sh
1
POST /oauth/token
2
Content-Type: application/x-www-form-urlencoded
3
4
grant_type=authorization_code&
5
client_id=&
6
client_secret=&
7
code=&
8
redirect_uri=
```
```json
1
{
2
"access_token": "...",
3
"refresh_token": "...",
4
"id_token": "...",
5
"expires_in": 299
6
}
```
Authorization codes expire after one use
Authorization codes are single-use and expire quickly (approximately 10 minutes). If you attempt to reuse a code or it expires, start a new login flow to obtain a fresh authorization code.
3. ## Manage sessions and token refresh
[Section titled “Manage sessions and token refresh”](#manage-sessions-and-token-refresh)
Store tokens in secure cookies and validate the access token on each request. When access tokens expire, use the refresh token to obtain new ones without requiring the user to re-authenticate.
**Token roles**
* **Access token** — Short-lived token (default 5 minutes) for authenticated API requests
* **Refresh token** — Long-lived token to obtain new access tokens
* **ID token** — JWT containing user identity claims; required for logout
Store tokens in secure, HttpOnly cookies with appropriate path scoping to limit exposure.
When an access token expires, request new tokens:
```sh
1
POST /oauth/token
2
Content-Type: application/x-www-form-urlencoded
3
4
grant_type=refresh_token&
5
client_id=&
6
client_secret=&
7
refresh_token=
```
Validate access tokens by verifying:
* Token signature using Scalekit’s public keys (JWKS endpoint)
* `iss` matches your Scalekit environment URL
* `aud` includes your `client_id`
* `exp` and `iat` are valid timestamps
Public keys for signature verification:
```sh
1
/keys
```
4. ## Implement logout
[Section titled “Implement logout”](#implement-logout)
Clear your application session and redirect to Scalekit’s logout endpoint to invalidate the shared session.
Your logout endpoint must:
* Extract the ID token before clearing cookies
* Clear application session cookies
* Redirect the browser to Scalekit’s logout endpoint
```sh
1
/oidc/logout?
2
id_token_hint=&
3
post_logout_redirect_uri=
```
Logout must be a browser redirect
Use a browser redirect to the `/oidc/logout` endpoint, not an API call. The redirect ensures Scalekit’s session cookie is sent with the request, allowing Scalekit to identify and terminate the correct session.
Configure [backchannel logout](/guides/dashboard/redirects/#back-channel-logout-url) URLs to receive notifications when a logout is performed from another application sharing the same user session.
## Handle errors
[Section titled “Handle errors”](#handle-errors)
When authentication fails, Scalekit redirects to your callback URL with error parameters instead of an authorization code:
```sh
/callback?error=access_denied&error_description=User+denied+access&state=
```
Check for errors before processing the authorization code:
* Check if the `error` parameter exists in the URL
* Log the `error` and `error_description` for debugging
* Display a user-friendly message
* Provide an option to retry login
Common error codes:
| Error | Description |
| ----------------- | ---------------------------------------- |
| `access_denied` | User denied the authorization request |
| `invalid_request` | Missing or invalid parameters |
| `server_error` | Scalekit encountered an unexpected error |
## (Optional) Use Scalekit Management APIs
[Section titled “(Optional) Use Scalekit Management APIs”](#optional-use-scalekit-management-apis)
In addition to handling user authentication, web applications can call Scalekit’s Management APIs from the backend. These APIs allow your application to interact with Scalekit-managed resources such as users, organizations, memberships, and roles.
Typical use cases include:
* Fetching the currently authenticated user
* Listing organizations the user belongs to
* Managing organization membership or roles
Management APIs are Scalekit-owned APIs intended for server-side use only. Enable Management API access in your application:
1. Go to **app.scalekit.com**
2. Navigate to **Developers > Applications**
3. Select your **Web Application**
4. Enable **Allow Scalekit Management API Access**
Management API access is only available for web applications
This option is only available for web applications because they can securely store credentials. When enabled, your backend can authenticate to Scalekit’s Management APIs using the application’s credentials. These calls are independent of end-user access tokens and are designed for trusted, server-side workflows.
## What’s next
[Section titled “What’s next”](#whats-next)
* [Configure backchannel logout](/guides/dashboard/redirects/#back-channel-logout-url) to receive notifications when a user logs out from another app
* [Set up a custom domain](/guides/custom-domain) for your authentication pages
* [Add enterprise SSO](/authenticate/auth-methods/enterprise-sso/) to support SAML and OIDC with your customers’ identity providers
---
# DOCUMENT BOUNDARY
---
# Quickstart
> Hosted auth pages, managed sessions, secure logout. Purpose built. Simple where it counts
You’ll implement sign-up, login, and logout flows with secure session management and user management included. The foundation you build here extends to features like workspaces, enterprise SSO, MCP authentication, and SCIM provisioning.
See Demo
[Play](https://youtube.com/watch?v=098_9blgM90)
See the integration in action
[Play](https://youtube.com/watch?v=Gnz8FYhHKI8)
Review the authentication sequence
Scalekit handles the complex authentication flow while you focus on your core product:
1. **User initiates sign-in** - Your app redirects to Scalekit’s hosted auth page
2. **Identity verification** - User authenticates via their preferred method
3. **Secure callback** - Scalekit returns user profile and session tokens
4. **Session creation** - Your app establishes a secure user session
5. **Protected access** - User accesses your application’s features
### Build with a coding agent
* Claude Code
```bash
/plugin marketplace add scalekit-inc/claude-code-authstack
```
```bash
/plugin install full-stack-auth@scalekit-auth-stack
```
* Codex
```bash
curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash
```
```bash
# Restart Codex
# Plugin Directory -> Scalekit Auth Stack -> install full-stack-auth
```
* GitHub Copilot CLI
```bash
copilot plugin marketplace add scalekit-inc/github-copilot-authstack
```
```bash
copilot plugin install full-stack-auth@scalekit-auth-stack
```
* 40+ agents
```bash
npx skills add scalekit-inc/skills --skill implementing-scalekit-fsa
```
[Continue building with AI →](/dev-kit/build-with-ai/full-stack-auth/)
***
1. ## Install Scalekit SDK
[Section titled “Install Scalekit SDK”](#install-scalekit-sdk)
Use the following instructions to install the SDK for your technology stack.
* Node.js
```bash
npm install @scalekit-sdk/node
```
* Python
```sh
pip install scalekit-sdk-python
```
* Go
```sh
go get -u github.com/scalekit-inc/scalekit-sdk-go
```
* Java
```groovy
/* Gradle users - add the following to your dependencies in build file */
implementation "com.scalekit:scalekit-sdk-java:2.0.11"
```
```xml
com.scalekit
scalekit-sdk-java
2.0.11
```
If you haven’t already, add your Scalekit credentials to your environment variables file:
.env
```sh
SCALEKIT_ENVIRONMENT_URL=
SCALEKIT_CLIENT_ID=
SCALEKIT_CLIENT_SECRET=
```
2. ## Redirect users to sign up (or) login
[Section titled “Redirect users to sign up (or) login”](#redirect-users-to-sign-up-or-login)
An authorization URL is an endpoint that redirects users to Scalekit’s sign-in page. Use the Scalekit SDK to construct this URL with your redirect URI and required scopes.
Register redirect URLs in your Scalekit dashboard
Before creating the authorization URL, register redirect URLs in your Scalekit dashboard. Go to **Scalekit dashboard** → **Authentication** → **Redirect URLs** and configure:
* **Allowed callback URL**: The endpoint where Scalekit sends users after successful authentication. The `redirect_uri` in your code must match this URL exactly. [Learn more](/guides/dashboard/redirects/#allowed-callback-urls)
* **Initiate-login URL**: Required when authentication is not initiated from your app-for example, when a user accepts an organization invitation or starts sign-in directly from their identity provider (IdP-initiated SSO). [Learn more](/guides/dashboard/redirects/#initiate-login-url)
Now, you can **create an authorization URL** to redirect users to the login page.
* Node.js
routes/auth.ts
```javascript
1
// Must match the allowed callback URL you registered in the dashboard
2
const redirectUri = 'http://localhost:3000/auth/callback';
3
4
// Request user profile data (openid, profile, email) and session tracking (offline_access)
5
// offline_access enables refresh tokens so users can stay logged in across sessions
6
const options = {
7
scopes: ['openid', 'profile', 'email', 'offline_access']
8
};
9
10
const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options);
11
// Generated URL will look like:
12
// https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth%2Fcallback
13
14
res.redirect(authorizationUrl);
```
* Python
app/auth/routes.py
```python
1
from scalekit import AuthorizationUrlOptions
2
3
# Must match the allowed callback URL you registered in the dashboard
4
redirect_uri = 'http://localhost:3000/auth/callback'
5
6
# Request user profile data (openid, profile, email) and session tracking (offline_access)
7
# offline_access enables refresh tokens so users can stay logged in across sessions
8
options = AuthorizationUrlOptions()
9
options.scopes = ['openid', 'profile', 'email', 'offline_access']
10
11
12
authorization_url = scalekit.get_authorization_url(redirect_uri, options)
13
# Generated URL will look like:
14
# https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback
15
16
return redirect(authorization_url)
```
* Go
internal/http/auth.go
```go
1
// Must match the allowed callback URL you registered in the dashboard
2
redirectUri := "http://localhost:3000/auth/callback"
3
4
// Request user profile data (openid, profile, email) and session tracking (offline_access)
5
// offline_access enables refresh tokens so users can stay logged in across sessions
6
options := scalekit.AuthorizationUrlOptions{
7
Scopes: []string{"openid", "profile", "email", "offline_access"}
8
}
9
10
authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options)
11
// Generated URL will look like:
12
// https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback
13
if err != nil {
14
// Handle error based on your application's error handling strategy
15
panic(err)
16
}
17
18
c.Redirect(http.StatusFound, authorizationUrl.String())
```
* Java
AuthController.java
```java
1
import com.scalekit.internal.http.AuthorizationUrlOptions;
2
import java.net.URL;
3
import java.util.Arrays;
4
5
// Must match the allowed callback URL you registered in the dashboard
6
String redirectUri = "http://localhost:3000/auth/callback";
7
8
// Request user profile data (openid, profile, email) and session tracking (offline_access)
9
// offline_access enables refresh tokens so users can stay logged in across sessions
10
AuthorizationUrlOptions options = new AuthorizationUrlOptions();
11
options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access"));
12
13
URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options);
14
// Generated URL will look like:
15
// https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback
```
This redirects users to Scalekit’s managed sign-in page where they can authenticate. The page includes default authentication methods for users to toggle between sign in and sign up.
Match your redirect URLs exactly
Ensure the redirect URL in your code matches what you configured in the Scalekit dashboard, including protocol (`https://`), domain, port, and path.
3. ## Get user details from the callback
[Section titled “Get user details from the callback”](#get-user-details-from-the-callback)
After successful authentication, Scalekit creates a user record and sends the user information to your callback endpoint. In authentication flow, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information and session tokens.
* Node.js
routes/auth-callback.ts
```javascript
1
import scalekit from '@/utils/auth.js'
2
const redirectUri = '';
3
4
// Get the authorization code from the scalekit initiated callback
5
app.get('/auth/callback', async (req, res) => {
6 collapsed lines
6
const { code, error, error_description } = req.query;
7
8
if (error) {
9
return res.status(401).json({ error, error_description });
10
}
11
12
try {
13
// Exchange the authorization code for user profile and session tokens
14
// Returns: user (profile info), idToken (JWT with user claims), accessToken (JWT with roles/permissions), refreshToken
15
const authResult = await scalekit.authenticateWithCode(
16
code, redirectUri
17
);
18
8 collapsed lines
19
const { user, idToken, accessToken, refreshToken } = authResult;
20
// idToken: Decode to access full user profile (sub, oid, email, name)
21
// accessToken: Contains roles and permissions for authorization decisions
22
// refreshToken: Use to obtain new access tokens when they expire
23
24
// "user" object contains the user's profile information
25
// Next step: Create a session and log in the user
26
res.redirect('/dashboard/profile');
27
} catch (err) {
28
console.error('Error exchanging code:', err);
29
res.status(500).json({ error: 'Failed to authenticate user' });
30
}
31
});
```
* Python
app/auth/callback.py
```python
6 collapsed lines
1
from flask import Flask, request, redirect, jsonify
2
from scalekit import ScalekitClient, CodeAuthenticationOptions
3
4
app = Flask(__name__)
5
# scalekit imported from your auth utils
6
7
redirect_uri = 'http://localhost:3000/auth/callback'
8
9
@app.route('/auth/callback')
10
def callback():
11
code = request.args.get('code')
12
error = request.args.get('error')
13
error_description = request.args.get('error_description')
14
15
if error:
16
return jsonify({'error': error, 'error_description': error_description}), 401
17
18
try:
19
# Exchange the authorization code for user profile and session tokens
20
# Returns: user (profile info), id_token (JWT with user claims), access_token (JWT with roles/permissions), refresh_token
21
options = CodeAuthenticationOptions()
22
auth_result = scalekit.authenticate_with_code(
23
code, redirect_uri, options
24
)
25
26
user = auth_result["user"]
27
# id_token: Decode to access full user profile (sub, oid, email, name)
28
# access_token: Contains roles and permissions for authorization decisions
4 collapsed lines
29
# refresh_token: Use to obtain new access tokens when they expire
30
31
# "user" object contains the user's profile information
32
# Next step: Create a session and log in the user
33
return redirect('/dashboard/profile')
34
except Exception as err:
35
print(f'Error exchanging code: {err}')
36
return jsonify({'error': 'Failed to authenticate user'}), 500
```
* Go
internal/http/auth\_callback.go
```go
17 collapsed lines
1
package main
2
3
import (
4
"log"
5
"net/http"
6
"os"
7
"github.com/gin-gonic/gin"
8
"github.com/scalekit-inc/scalekit-sdk-go"
9
)
10
11
// Create Scalekit client instance
12
var scalekitClient = scalekit.NewScalekitClient(
13
os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
14
os.Getenv("SCALEKIT_CLIENT_ID"),
15
os.Getenv("SCALEKIT_CLIENT_SECRET"),
16
)
17
18
const redirectUri = "http://localhost:3000/auth/callback"
19
20
func callbackHandler(c *gin.Context) {
21
code := c.Query("code")
22
errorParam := c.Query("error")
23
errorDescription := c.Query("error_description")
9 collapsed lines
24
25
if errorParam != "" {
26
c.JSON(http.StatusUnauthorized, gin.H{
27
"error": errorParam,
28
"error_description": errorDescription,
29
})
30
return
31
}
32
33
// Exchange the authorization code for user profile and session tokens
34
// Returns: User (profile info), IdToken (JWT with user claims), AccessToken (JWT with roles/permissions), RefreshToken
35
options := scalekit.AuthenticationOptions{}
36
authResult, err := scalekitClient.AuthenticateWithCode(
37
c.Request.Context(), code, redirectUri, options,
9 collapsed lines
38
)
39
40
if err != nil {
41
log.Printf("Error exchanging code: %v", err)
42
c.JSON(http.StatusInternalServerError, gin.H{
43
"error": "Failed to authenticate user",
44
})
45
return
46
}
47
48
user := authResult.User
49
// IdToken: Decode to access full user profile (sub, oid, email, name)
50
// AccessToken: Contains roles and permissions for authorization decisions
51
// RefreshToken: Use to obtain new access tokens when they expire
52
53
// "user" object contains the user's profile information
54
// Next step: Create a session and log in the user
55
c.Redirect(http.StatusFound, "/dashboard/profile")
56
}
```
* Java
CallbackController.java
```java
10 collapsed lines
1
import com.scalekit.ScalekitClient;
2
import com.scalekit.internal.http.AuthenticationOptions;
3
import com.scalekit.internal.http.AuthenticationResponse;
4
import org.springframework.web.bind.annotation.*;
5
import org.springframework.web.servlet.view.RedirectView;
6
import org.springframework.http.ResponseEntity;
7
import org.springframework.http.HttpStatus;
8
import java.util.HashMap;
9
import java.util.Map;
10
11
@RestController
12
public class CallbackController {
13
14
private final String redirectUri = "http://localhost:3000/auth/callback";
15
16
@GetMapping("/auth/callback")
17
public Object callback(
18
@RequestParam(required = false) String code,
19
@RequestParam(required = false) String error,
20
@RequestParam(name = "error_description", required = false) String errorDescription
21
) {
4 collapsed lines
22
if (error != null) {
23
// handle error
24
}
25
26
try {
27
// Exchange the authorization code for user profile and session tokens
28
// Returns: user (profile info), idToken (JWT with user claims), accessToken (JWT with roles/permissions), refreshToken
29
AuthenticationOptions options = new AuthenticationOptions();
30
AuthenticationResponse authResult = scalekit
31
.authentication()
32
.authenticateWithCode(code,redirectUri,options);
33
34
var user = authResult.getIdTokenClaims();
35
// idToken: Decode to access full user profile (sub, oid, email, name)
36
// accessToken: Contains roles and permissions for authorization decisions
37
// refreshToken: Use to obtain new access tokens when they expire
38
39
// "user" object contains the user's profile information
8 collapsed lines
40
// Next step: Create a session and log in the user
41
return new RedirectView("/dashboard/profile");
42
43
} catch (Exception err) {
44
// Handle exception (e.g., log error, return error response)
45
}
46
}
47
}
```
The `authResult` object contains:
* `user` - Common user details with email, name, and verification status
* `idToken` - JWT containing verified full user identity claims (includes: `sub` user ID, `oid` organization ID, `email`, `name`, `exp` expiration)
* `accessToken` - Short-lived token that determines current access context (includes: `sub` user ID, `oid` organization ID, `roles`, `permissions`, `exp` expiration)
* `refreshToken` - Long-lived token to obtain new access tokens
- 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
}
```
The user details are packaged in the form of JWT tokens. Decode the `idToken` to access full user profile information (email, name, organization ID) and the `accessToken` to check user roles and permissions for authorization decisions. See [Complete login with code exchange](/authenticate/fsa/complete-login/) for detailed token claim references and verification instructions.
4. ## Create and manage user sessions
[Section titled “Create and manage user sessions”](#create-and-manage-user-sessions)
The access token is a JWT that contains the user’s permissions and roles. It expires in 5 minutes (default) but [can be configured](/authenticate/fsa/manage-session/#configure-session-security-and-duration). When it expires, use the refresh token to obtain a new access token. The refresh token is long-lived and designed for this purpose.
The Scalekit SDK provides methods to refresh access tokens automatically. However, you must log the user out when the refresh token itself expires or becomes invalid.
* Node.js
```javascript
4 collapsed lines
1
import cookieParser from 'cookie-parser';
2
// Set cookie parser middleware
3
app.use(cookieParser());
4
5
// Store access token in HttpOnly cookie with Path scoping to API routes
6
res.cookie('accessToken', authResult.accessToken, {
7
maxAge: (authResult.expiresIn - 60) * 1000,
8
httpOnly: true,
9
secure: true,
10
path: '/api',
11
sameSite: 'strict'
12
});
13
14
// Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint
15
res.cookie('refreshToken', authResult.refreshToken, {
16
httpOnly: true,
17
secure: true,
18
path: '/auth/refresh',
19
sameSite: 'strict'
20
});
```
* Python
```python
10 collapsed lines
1
from flask import Flask, make_response
2
import os
3
4
# Cookie parsing is built-in with Flask's request object
5
app = Flask(__name__)
6
7
response = make_response()
8
9
# Store access token in HttpOnly cookie with Path scoping to API routes
10
response.set_cookie(
11
'accessToken',
12
auth_result.access_token,
13
max_age=auth_result.expires_in - 60, # seconds in Flask
14
httponly=True,
15
secure=True,
16
path='/api',
17
samesite='Strict'
18
)
19
20
# Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint
21
response.set_cookie(
22
'refreshToken',
23
auth_result.refresh_token,
24
httponly=True,
25
secure=True,
26
path='/auth/refresh',
27
samesite='Strict'
28
)
```
* Go
```go
8 collapsed lines
1
import (
2
"net/http"
3
"os"
4
)
5
6
// Set SameSite mode for CSRF protection
7
c.SetSameSite(http.SameSiteStrictMode)
8
9
// Store access token in HttpOnly cookie with Path scoping to API routes
10
c.SetCookie(
11
"accessToken",
12
authResult.AccessToken,
13
authResult.ExpiresIn-60, // seconds in Gin
14
"/api",
15
"",
16
os.Getenv("GIN_MODE") == "release",
17
true,
18
)
19
20
// Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint
21
c.SetCookie(
22
"refreshToken",
23
authResult.RefreshToken,
24
0, // No expiry for refresh token cookie
25
"/auth/refresh",
26
"",
27
os.Getenv("GIN_MODE") == "release",
28
true,
29
)
```
* Java
```java
6 collapsed lines
1
import javax.servlet.http.Cookie;
2
import javax.servlet.http.HttpServletResponse;
3
4
// Store access token in HttpOnly cookie with Path scoping to API routes
5
Cookie accessTokenCookie = new Cookie("accessToken", authResult.getAccessToken());
6
accessTokenCookie.setMaxAge(authResult.getExpiresIn() - 60); // seconds in Spring
7
accessTokenCookie.setHttpOnly(true);
8
accessTokenCookie.setSecure(true);
9
accessTokenCookie.setPath("/api");
10
response.addCookie(accessTokenCookie);
11
12
// Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint
13
Cookie refreshTokenCookie = new Cookie("refreshToken", authResult.getRefreshToken());
14
refreshTokenCookie.setHttpOnly(true);
15
refreshTokenCookie.setSecure(true);
16
refreshTokenCookie.setPath("/auth/refresh");
17
response.addCookie(refreshTokenCookie);
18
response.setHeader("Set-Cookie",
19
response.getHeader("Set-Cookie") + "; SameSite=Strict");
```
This sets browser cookies with the session tokens. Every request to your backend needs to verify the `accessToken` to ensure the user is authenticated. If expired, use the `refreshToken` to get a new access token.
* Node.js
```javascript
1
// Middleware to verify and refresh tokens if needed
2
const verifyToken = async (req, res, next) => {
3
try {
4
// Get access token from cookie and decrypt it
5
const accessToken = req.cookies.accessToken;
6
const decryptedAccessToken = decrypt(accessToken);
7
4 collapsed lines
8
if (!accessToken) {
9
return res.status(401).json({ message: 'No access token provided' });
10
}
11
12
// Use Scalekit SDK to validate the token
13
const isValid = await scalekit.validateAccessToken(decryptedAccessToken);
14
15
if (!isValid) {
16
// Use stored refreshToken to get a new access token
17
const {
18
user,
19
idToken,
20
accessToken,
21
refreshToken: newRefreshToken,
22
} = await scalekit.refreshAccessToken(refreshToken);
23
24
// Store the new refresh token
25
// Update the cookie with the new access token
12 collapsed lines
26
}
27
next();
28
};
29
30
// Example of using the middleware to protect routes
31
app.get('/dashboard', verifyToken, (req, res) => {
32
// The user object is now available in req.user
33
res.json({
34
message: 'This is a protected route',
35
user: req.user
36
});
37
});
```
* Python
```python
3 collapsed lines
1
from functools import wraps
2
from flask import request, jsonify, make_response
3
4
def verify_token(f):
5
"""Decorator to verify and refresh tokens if needed"""
6
@wraps(f)
7
def decorated_function(*args, **kwargs):
8
try:
9
# Get access token from cookie
10
access_token = request.cookies.get('accessToken')
4 collapsed lines
11
12
if not access_token:
13
return jsonify({'message': 'No access token provided'}), 401
14
15
# Decrypt the accessToken using the same encryption algorithm
16
decrypted_access_token = decrypt(access_token)
17
18
# Use Scalekit SDK to validate the token
19
is_valid = scalekit.validate_access_token(decrypted_access_token)
20
21
if not is_valid:
6 collapsed lines
22
# Get stored refresh token
23
refresh_token = get_stored_refresh_token()
24
25
if not refresh_token:
26
return jsonify({'message': 'No refresh token available'}), 401
27
28
# Use stored refreshToken to get a new access token
29
token_response = scalekit.refresh_access_token(refresh_token)
30
31
# Python SDK returns dict with access_token and refresh_token
32
new_access_token = token_response.get('access_token')
33
new_refresh_token = token_response.get('refresh_token')
34
35
# Store the new refresh token
36
store_refresh_token(new_refresh_token)
37
38
# Update the cookie with the new access token
39
encrypted_new_access_token = encrypt(new_access_token)
40
response = make_response(f(*args, **kwargs))
41
response.set_cookie(
42
'accessToken',
43
encrypted_new_access_token,
44
httponly=True,
45
secure=True,
46
path='/',
47
samesite='Strict'
48
)
49
50
return response
17 collapsed lines
51
52
# If the token was valid we just invoke the view as-is
53
return f(*args, **kwargs)
54
55
except Exception as e:
56
return jsonify({'message': f'Token verification failed: {str(e)}'}), 401
57
58
return decorated_function
59
60
# Example of using the decorator to protect routes
61
@app.route('/dashboard')
62
@verify_token
63
def dashboard():
64
return jsonify({
65
'message': 'This is a protected route',
66
'user': getattr(request, 'user', None)
67
})
```
* Go
```go
5 collapsed lines
1
import (
2
"context"
3
"net/http"
4
)
5
6
// verifyToken is a middleware that ensures a valid access token or refreshes it if expired.
7
func verifyToken(next http.HandlerFunc) http.HandlerFunc {
8
return func(w http.ResponseWriter, r *http.Request) {
9
// Retrieve the access token from the user's cookie
10
cookie, err := r.Cookie("accessToken")
4 collapsed lines
11
if err != nil {
12
// No access token cookie found; reject the request
13
http.Error(w, `{"message": "No access token provided"}`, http.StatusUnauthorized)
14
return
15
}
16
17
accessToken := cookie.Value
18
19
// Decrypt the access token before validation
20
decryptedAccessToken, err := decrypt(accessToken)
5 collapsed lines
21
if err != nil {
22
// Could not decrypt access token; treat as invalid
23
http.Error(w, `{"message": "Token decryption failed"}`, http.StatusUnauthorized)
24
return
25
}
26
27
// Validate the access token using the Scalekit SDK
28
isValid, err := scalekitClient.ValidateAccessToken(r.Context(), decryptedAccessToken)
29
if err != nil || !isValid {
30
// Access token is invalid or expired
31
32
// Attempt to retrieve the stored refresh token
33
refreshToken, err := getStoredRefreshToken(r)
5 collapsed lines
34
if err != nil {
35
// No refresh token is available; cannot continue
36
http.Error(w, `{"message": "No refresh token available"}`, http.StatusUnauthorized)
37
return
38
}
39
40
// Use the refresh token to obtain a new access token from Scalekit
41
tokenResponse, err := scalekitClient.RefreshAccessToken(r.Context(), refreshToken)
5 collapsed lines
42
if err != nil {
43
// Refresh attempt failed; likely an expired or invalid refresh token
44
http.Error(w, `{"message": "Token refresh failed"}`, http.StatusUnauthorized)
45
return
46
}
47
48
// Save the new refresh token so it can be reused for future requests
49
err = storeRefreshToken(tokenResponse.RefreshToken)
5 collapsed lines
50
if err != nil {
51
// Could not store the new refresh token
52
http.Error(w, `{"message": "Failed to store refresh token"}`, http.StatusInternalServerError)
53
return
54
}
55
56
// Encrypt the new access token before setting it in the cookie
57
encryptedNewAccessToken, err := encrypt(tokenResponse.AccessToken)
5 collapsed lines
58
if err != nil {
59
// Could not encrypt new access token
60
http.Error(w, `{"message": "Token encryption failed"}`, http.StatusInternalServerError)
61
return
62
}
63
64
// Issue a new accessToken cookie with updated credentials
31 collapsed lines
65
newCookie := &http.Cookie{
66
Name: "accessToken",
67
Value: encryptedNewAccessToken,
68
HttpOnly: true,
69
Secure: true,
70
Path: "/",
71
SameSite: http.SameSiteStrictMode,
72
}
73
http.SetCookie(w, newCookie)
74
75
// Mark the token as valid in the request context and proceed
76
r = r.WithContext(context.WithValue(r.Context(), "tokenValid", true))
77
} else {
78
// The access token is valid; continue with marked context
79
r = r.WithContext(context.WithValue(r.Context(), "tokenValid", true))
80
}
81
82
// Pass the request along to the next handler in the chain
83
next(w, r)
84
}
85
}
86
87
// dashboardHandler demonstrates a protected route that requires authentication.
88
func dashboardHandler(w http.ResponseWriter, r *http.Request) {
89
w.Header().Set("Content-Type", "application/json")
90
w.Write([]byte(`{
91
"message": "This is a protected route",
92
"tokenValid": true
93
}`))
94
}
95
96
// Usage example:
97
// Attach middleware to the /dashboard route:
98
// http.HandleFunc("/dashboard", verifyToken(dashboardHandler))
```
* Java
```java
6 collapsed lines
1
import javax.servlet.http.HttpServletRequest;
2
import javax.servlet.http.HttpServletResponse;
3
import javax.servlet.http.Cookie;
4
import org.springframework.web.servlet.HandlerInterceptor;
5
6
@Component
7
public class TokenVerificationInterceptor implements HandlerInterceptor {
8
@Override
9
public boolean preHandle(
10
HttpServletRequest request,
11
HttpServletResponse response,
12
Object handler
13
) throws Exception {
14
try {
15
// Get access token from cookie
16
String accessToken = getCookieValue(request, "accessToken");
17
String refreshToken = getCookieValue(request, "refreshToken");
18
19
// Decrypt the tokens
20
String decryptedAccessToken = decrypt(accessToken);
21
String decryptedRefreshToken = decrypt(refreshToken);
22
23
// Use Scalekit SDK to validate the token
24
boolean isValid = scalekit.authentication().validateAccessToken(decryptedAccessToken);
25
26
27
// Use refreshToken to get a new access token
28
AuthenticationResponse tokenResponse = scalekit
29
.authentication()
30
.refreshToken(decryptedRefreshToken);
31
32
// Update the cookie with the new access token and refresh token
33
String encryptedNewAccessToken = encrypt(tokenResponse.getAccessToken());
34
String encryptedNewRefreshToken = encrypt(tokenResponse.getRefreshToken());
35
36
Cookie accessTokenCookie = new Cookie("accessToken", encryptedNewAccessToken);
37
accessTokenCookie.setHttpOnly(true);
38
accessTokenCookie.setSecure(true);
39
accessTokenCookie.setPath("/");
40
response.addCookie(accessTokenCookie);
41
42
Cookie refreshTokenCookie = new Cookie("refreshToken", encryptedNewRefreshToken);
43
refreshTokenCookie.setHttpOnly(true);
44
refreshTokenCookie.setSecure(true);
45
refreshTokenCookie.setPath("/");
46
response.addCookie(refreshTokenCookie);
47
48
return true;
49
} catch (Exception e) {
50
// handle exception
51
}
52
}
13 collapsed lines
53
54
private String getCookieValue(HttpServletRequest request, String cookieName) {
55
Cookie[] cookies = request.getCookies();
56
if (cookies != null) {
57
for (Cookie cookie : cookies) {
58
if (cookieName.equals(cookie.getName())) {
59
return cookie.getValue();
60
}
61
}
62
}
63
return null;
64
}
65
}
```
Authenticated users can access your dashboard. The app enforces session policies using session tokens. To change session policies, go to Dashboard > Authentication > Session Policy in the Scalekit dashboard.
5. ## Log out the user
[Section titled “Log out the user”](#log-out-the-user)
Session persistence depends on the session policy configured in the Scalekit dashboard. To log out a user, clear local session data and invalidate the user’s session in Scalekit.
* Node.js
```javascript
1
app.get('/logout', (req, res) => {
2
// Clear all session data including cookies and local storage
3
clearSessionData();
4
5
const logoutUrl = scalekit.getLogoutUrl(
6
idTokenHint, // ID token to invalidate
7
postLogoutRedirectUri // URL that scalekit redirects after session invalidation
8
);
9
10
// Redirect the user to the Scalekit logout endpoint to begin invalidating the session.
11
res.redirect(logoutUrl); // This URL can only be used once and expires after logout.
12
});
```
* Python
```python
5 collapsed lines
1
from flask import Flask, redirect
2
from scalekit.common.scalekit import LogoutUrlOptions
3
4
app = Flask(__name__)
5
6
@app.route('/logout')
7
def logout():
8
# Clear all session data including cookies and local storage
9
clear_session_data()
10
11
# Generate Scalekit logout URL
12
options = LogoutUrlOptions(
13
id_token_hint=id_token,
14
post_logout_redirect_uri=post_logout_redirect_uri
15
)
16
logout_url = scalekit.get_logout_url(options)
17
18
# Redirect to Scalekit's logout endpoint
19
# Note: This is a one-time use URL that becomes invalid after use
20
return redirect(logout_url)
```
* Go
```go
8 collapsed lines
1
package main
2
3
import (
4
"net/http"
5
"github.com/gin-gonic/gin"
6
"github.com/scalekit-inc/scalekit-sdk-go"
7
)
8
9
func logoutHandler(c *gin.Context) {
10
// Clear all session data including cookies and local storage
11
clearSessionData()
12
13
// Generate Scalekit logout URL
14
options := scalekit.LogoutUrlOptions{
15
IdTokenHint: idToken,
16
PostLogoutRedirectUri: postLogoutRedirectUri,
17
}
18
logoutUrl, err := scalekitClient.GetLogoutUrl(options)
19
if err != nil {
20
c.JSON(http.StatusInternalServerError, gin.H{
21
"error": "Failed to generate logout URL",
22
})
23
return
24
}
25
26
// Redirect to Scalekit's logout endpoint
27
// Note: This is a one-time use URL that becomes invalid after use
28
c.Redirect(http.StatusFound, logoutUrl.String())
29
}
```
* Java
```java
5 collapsed lines
1
import com.scalekit.internal.http.LogoutUrlOptions;
2
import org.springframework.web.bind.annotation.*;
3
import org.springframework.web.servlet.view.RedirectView;
4
import java.net.URL;
5
6
@RestController
7
public class LogoutController {
8
9
@GetMapping("/logout")
10
public RedirectView logout() {
11
12
clearSessionData();
13
14
15
LogoutUrlOptions options = new LogoutUrlOptions();
16
options.setIdTokenHint(idToken);
17
options.setPostLogoutRedirectUri(postLogoutRedirectUri);
18
19
URL logoutUrl = scalekit.authentication()
20
.getLogoutUrl(options);
21
22
23
// Note: This is a one-time use URL that becomes invalid after use
24
return new RedirectView(logoutUrl.toString());
25
}
26
}
```
The logout process completes when Scalekit invalidates the user’s session and redirects them to your [registered post-logout URL](/guides/dashboard/redirects/#post-logout-url).
This single integration unlocks multiple authentication methods, including Magic Link & OTP, social sign-ins, enterprise single sign-on (SSO), and robust user management features. As you continue working with Scalekit, you’ll discover even more features that enhance your authentication workflows.
---
# DOCUMENT BOUNDARY
---
# User management settings
> Configure user management settings, including user attributes and configuration options from to Scalekit dashboard.
User management settings allow you to configure how user data is handled in the environment and what attributes are available for users in your application. These settings are accessible from the **User Management** section in the Scalekit dashboard.
The Configuration tab provides several important settings that control user registration, organization limits, and branding.
### Sign-up for your application
[Section titled “Sign-up for your application”](#sign-up-for-your-application)
Control whether users can sign up and create new organizations. When enabled, users can register for your application and automatically create a new organization.
### Organization creation limit per user
[Section titled “Organization creation limit per user”](#organization-creation-limit-per-user)
Define the maximum number of organizations a single user can create. This helps prevent abuse and manage resource usage across your application.
### Limit user sign-ups in an organization
[Section titled “Limit user sign-ups in an organization”](#limit-user-sign-ups-in-an-organization)
Use this when you need seat caps per organization—for example, when organizations map to departments or when plans include per‑org seat limits.
To set a limit from the dashboard:
1. Go to Organizations → Select an Organization → User management
2. Find Organization limits and set max users per organization. Save changes.
New users provisioning to this organizations are blocked until limits are increased. Configure them by updating the organization settings.
Note
This limit includes users in states “active” and “pending invite”. Expired invites do not count toward the limit.
### Invitation expiry
[Section titled “Invitation expiry”](#invitation-expiry)
Configure how long user invitation links remain valid. The default setting of **15 days** ensures that invitations don’t remain active indefinitely, improving security while giving invitees reasonable time to accept.
### Organization meta name
[Section titled “Organization meta name”](#organization-meta-name)
Customize what you call an “Organization” in your application. This meta name appears throughout all Scalekit-hosted pages. For example, you might call it:
* “Company” for B2B applications
* “Team” for collaboration tools
* “Workspace” for productivity apps
* “Account” for multi-tenant systems
## User attributes
[Section titled “User attributes”](#user-attributes)
The User Attributes tab allows you to define custom fields that will be available for user profiles. These attributes help you collect and store additional information about your users beyond the standard profile fields.
When you define custom user attributes, they become part of the user’s profile data that your application can access. This allows you to:
* Collect additional information during user registration
* Store application-specific user data
* Personalize user experiences based on these attributes
* Use the data for application logic and user management
---
# DOCUMENT BOUNDARY
---
# Handle webhook events in your application
> Receive real-time notifications about authentication events in your application using Scalekit webhooks
Webhooks provide real-time notifications about authentication and user management events in your Scalekit environment. Instead of polling for changes, your application receives instant notifications when users sign up, log in, join organizations, or when other important events occur.
Webhooks enable your app to react immediately to changes in your auth stack through:
* **Real-time updates**: Get notified immediately when events occur
* **Reduced API calls**: No need to poll for changes
* **Event-driven architecture**: Build responsive workflows that react to user actions
* **Reliable delivery**: Scalekit ensures webhook delivery with automatic retries
## Webhook event object
[Section titled “Webhook event object”](#webhook-event-object)
All webhook payloads follow a standardized structure with metadata and event-specific data in the `data` field.
User created event payload
```json
{
"spec_version": "1", // The version of the event specification format. Currently "1".
"id": "evt_123456789", // A unique identifier for the event (e.g., evt_123456789).
"object": "DirectoryUser", // The type of object that triggered the event (e.g., "DirectoryUser", "Directory", "Connection").
"environment_id": "env_123456789", // The ID of the environment where the event occurred.
"occurred_at": "2024-08-21T10:20:17.072Z", // ISO 8601 timestamp indicating when the event occurred.
"organization_id": "org_123456789", // The ID of the organization associated with the event.
"type": "organization.directory.user_created", // The specific event type (e.g., "organization.directory.user_created").
"data": { // Event-specific payload containing details relevant to the event type.
"user_id": "usr_123456789",
"email": "user@example.com",
"name": "John Doe"
}
}
```
## Configure webhooks in the dashboard
[Section titled “Configure webhooks in the dashboard”](#configure-webhooks-in-the-dashboard)
Set up webhook endpoints and select which events you want to receive through the Scalekit dashboard.
1. In your Scalekit dashboard, navigate to **Settings** > **Webhooks**
2. Click **Add Endpoint** and provide:
* **Endpoint URL** - Your application’s webhook handler URL (e.g., `https://yourapp.com/webhooks/scalekit`)
* **Description** - Optional description for this endpoint
3. Choose which events you want to receive from the dropdown:
* **User events** - `user.created`, `user.updated`, `user.deleted`
* **Organization events** - `organization.created`, `organization.updated`
* **Authentication events** - `session.created`, `session.expired`
* **Membership events** - `membership.created`, `membership.updated`, `membership.deleted`
4. Copy the **Signing Secret** - you’ll use this to verify webhook authenticity in your application
5. Use the **Send Test Event** button to verify your endpoint is working correctly
Webhook response requirements
Your webhook endpoint should respond with a `201` status code within 10 seconds to be considered successful. Failed deliveries are retried up to 3 times with exponential backoff.
## Implement webhook handlers
[Section titled “Implement webhook handlers”](#implement-webhook-handlers)
Create secure webhook handlers in your application to process incoming events from Scalekit.
1. ### Set up webhook endpoint
[Section titled “Set up webhook endpoint”](#set-up-webhook-endpoint)
Create an HTTP POST endpoint in your application to receive webhook payloads from Scalekit.
* Node.js
Express.js webhook handler
```javascript
3 collapsed lines
1
import express from 'express';
2
import { Scalekit } from '@scalekit-sdk/node';
3
4
const app = express();
5
const scalekit = new Scalekit(/* your credentials */);
6
7
// Use raw body parser for webhook signature verification
8
app.use('/webhooks/scalekit', express.raw({ type: 'application/json' }));
9
10
app.post('/webhooks/scalekit', async (req, res) => {
11
try {
12
// Get webhook signature from headers
13
const signature = req.headers['scalekit-signature'];
14
const rawBody = req.body;
15
16
// Verify webhook signature using Scalekit SDK
17
const isValid = await scalekit.webhooks.verifySignature(
18
rawBody,
19
signature,
20
process.env.SCALEKIT_WEBHOOK_SECRET
21
);
22
23
if (!isValid) {
24
console.error('Invalid webhook signature');
25
return res.status(401).json({ error: 'Invalid signature' });
26
}
27
28
// Parse and process the webhook payload
29
const event = JSON.parse(rawBody.toString());
30
await processWebhookEvent(event);
31
32
// Always respond with 200 to acknowledge receipt
33
res.status(200).json({ received: true });
34
35
} catch (error) {
36
console.error('Webhook processing error:', error);
37
res.status(500).json({ error: 'Webhook processing failed' });
38
}
39
});
```
* Python
Flask webhook handler
```python
4 collapsed lines
1
from flask import Flask, request, jsonify
2
import json
3
from scalekit import ScalekitClient
4
5
app = Flask(__name__)
6
scalekit_client = ScalekitClient(/* your credentials */)
7
8
@app.route('/webhooks/scalekit', methods=['POST'])
9
def handle_webhook():
10
try:
11
# Get webhook signature from headers
12
signature = request.headers.get('scalekit-signature')
13
raw_body = request.get_data()
14
15
# Verify webhook signature using Scalekit SDK
16
is_valid = scalekit_client.webhooks.verify_signature(
17
raw_body,
18
signature,
19
os.environ.get('SCALEKIT_WEBHOOK_SECRET')
20
)
21
22
if not is_valid:
23
print('Invalid webhook signature')
24
return jsonify({'error': 'Invalid signature'}), 401
25
26
# Parse and process the webhook payload
27
event = json.loads(raw_body.decode('utf-8'))
28
process_webhook_event(event)
29
30
# Always respond with 200 to acknowledge receipt
31
return jsonify({'received': True}), 200
32
33
except Exception as error:
34
print(f'Webhook processing error: {error}')
35
return jsonify({'error': 'Webhook processing failed'}), 500
```
* Go
Gin webhook handler
```go
8 collapsed lines
1
package main
2
3
import (
4
"encoding/json"
5
"io"
6
"net/http"
7
"github.com/gin-gonic/gin"
8
"github.com/scalekit-inc/scalekit-sdk-go"
9
)
10
11
scalekitClient := scalekit.NewScalekitClient(/* your credentials */)
12
13
func handleWebhook(c *gin.Context) {
14
// Get webhook signature from headers
15
signature := c.GetHeader("scalekit-signature")
16
17
// Read raw body
18
rawBody, err := io.ReadAll(c.Request.Body)
19
if err != nil {
20
c.JSON(http.StatusBadRequest, gin.H{"error": "Failed to read body"})
21
return
22
}
23
24
// Verify webhook signature using Scalekit SDK
25
isValid, err := scalekitClient.Webhooks.VerifySignature(
26
rawBody,
27
signature,
28
os.Getenv("SCALEKIT_WEBHOOK_SECRET"),
29
)
30
31
if err != nil || !isValid {
32
c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid signature"})
33
return
34
}
35
36
// Parse and process the webhook payload
37
var event map[string]interface{}
38
if err := json.Unmarshal(rawBody, &event); err != nil {
39
c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid JSON"})
40
return
41
}
42
43
processWebhookEvent(event)
44
45
// Always respond with 200 to acknowledge receipt
46
c.JSON(http.StatusOK, gin.H{"received": true})
47
}
```
* Java
Spring webhook handler
```java
8 collapsed lines
1
import org.springframework.web.bind.annotation.*;
2
import org.springframework.http.ResponseEntity;
3
import org.springframework.http.HttpStatus;
4
import com.scalekit.ScalekitClient;
5
import com.fasterxml.jackson.databind.ObjectMapper;
6
import javax.servlet.http.HttpServletRequest;
7
import java.io.IOException;
8
9
@RestController
10
public class WebhookController {
11
12
private final ScalekitClient scalekitClient;
13
private final ObjectMapper objectMapper = new ObjectMapper();
14
15
@PostMapping("/webhooks/scalekit")
16
public ResponseEntity> handleWebhook(
17
HttpServletRequest request,
18
@RequestBody String rawBody
19
) {
20
try {
21
// Get webhook signature from headers
22
String signature = request.getHeader("scalekit-signature");
23
24
// Verify webhook signature using Scalekit SDK
25
boolean isValid = scalekitClient.webhooks().verifySignature(
26
rawBody.getBytes(),
27
signature,
28
System.getenv("SCALEKIT_WEBHOOK_SECRET")
29
);
30
31
if (!isValid) {
32
return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
33
.body(Map.of("error", "Invalid signature"));
34
}
35
36
// Parse and process the webhook payload
37
Map event = objectMapper.readValue(rawBody, Map.class);
38
processWebhookEvent(event);
39
40
// Always respond with 200 to acknowledge receipt
41
return ResponseEntity.ok(Map.of("received", true));
42
43
} catch (Exception error) {
44
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
45
.body(Map.of("error", "Webhook processing failed"));
46
}
47
}
48
}
```
2. ### Process webhook events
[Section titled “Process webhook events”](#process-webhook-events)
Handle different event types based on your application’s needs.
* Node.js
Process webhook events
```javascript
1
async function processWebhookEvent(event) {
2
console.log(`Processing event: ${event.type}`);
3
4
switch (event.type) {
5
case 'user.created':
6
// Handle new user registration
7
await handleUserCreated(event.data.user, event.data.organization);
8
break;
9
10
case 'user.updated':
11
// Handle user profile updates
12
await handleUserUpdated(event.data.user);
13
break;
14
15
case 'organization.created':
16
// Handle new organization creation
17
await handleOrganizationCreated(event.data.organization);
18
break;
19
20
case 'membership.created':
21
// Handle user joining organization
22
await handleMembershipCreated(event.data.membership);
23
break;
24
25
default:
26
console.log(`Unhandled event type: ${event.type}`);
27
}
28
}
29
30
async function handleUserCreated(user, organization) {
31
// Use case: Sync new user to your database, send welcome email, set up user workspace
32
console.log(`New user created: ${user.email} in org: ${organization.display_name}`);
33
34
// Sync to your database
35
await syncUserToDatabase(user, organization);
36
37
// Send welcome email
38
await sendWelcomeEmail(user.email, user.first_name);
39
40
// Set up user workspace or default settings
41
await setupUserDefaults(user.id, organization.id);
42
}
```
* Python
Process webhook events
```python
1
def process_webhook_event(event):
2
print(f'Processing event: {event["type"]}')
3
4
event_type = event['type']
5
event_data = event['data']
6
7
if event_type == 'user.created':
8
# Handle new user registration
9
handle_user_created(event_data['user'], event_data['organization'])
10
elif event_type == 'user.updated':
11
# Handle user profile updates
12
handle_user_updated(event_data['user'])
13
elif event_type == 'organization.created':
14
# Handle new organization creation
15
handle_organization_created(event_data['organization'])
16
elif event_type == 'membership.created':
17
# Handle user joining organization
18
handle_membership_created(event_data['membership'])
19
else:
20
print(f'Unhandled event type: {event_type}')
21
22
def handle_user_created(user, organization):
23
# Use case: Sync new user to your database, send welcome email, set up user workspace
24
print(f'New user created: {user["email"]} in org: {organization["display_name"]}')
25
26
# Sync to your database
27
sync_user_to_database(user, organization)
28
29
# Send welcome email
30
send_welcome_email(user['email'], user['first_name'])
31
32
# Set up user workspace or default settings
33
setup_user_defaults(user['id'], organization['id'])
```
* Go
Process webhook events
```go
1
func processWebhookEvent(event map[string]interface{}) {
2
eventType := event["type"].(string)
3
eventData := event["data"].(map[string]interface{})
4
5
fmt.Printf("Processing event: %s\n", eventType)
6
7
switch eventType {
8
case "user.created":
9
// Handle new user registration
10
user := eventData["user"].(map[string]interface{})
11
organization := eventData["organization"].(map[string]interface{})
12
handleUserCreated(user, organization)
13
14
case "user.updated":
15
// Handle user profile updates
16
user := eventData["user"].(map[string]interface{})
17
handleUserUpdated(user)
18
19
case "organization.created":
20
// Handle new organization creation
21
organization := eventData["organization"].(map[string]interface{})
22
handleOrganizationCreated(organization)
23
24
case "membership.created":
25
// Handle user joining organization
26
membership := eventData["membership"].(map[string]interface{})
27
handleMembershipCreated(membership)
28
29
default:
30
fmt.Printf("Unhandled event type: %s\n", eventType)
31
}
32
}
33
34
func handleUserCreated(user, organization map[string]interface{}) {
35
// Use case: Sync new user to your database, send welcome email, set up user workspace
36
fmt.Printf("New user created: %s in org: %s\n",
37
user["email"], organization["display_name"])
38
39
// Sync to your database
40
syncUserToDatabase(user, organization)
41
42
// Send welcome email
43
sendWelcomeEmail(user["email"].(string), user["first_name"].(string))
44
45
// Set up user workspace or default settings
46
setupUserDefaults(user["id"].(string), organization["id"].(string))
47
}
```
* Java
Process webhook events
```java
1
private void processWebhookEvent(Map event) {
2
String eventType = (String) event.get("type");
3
Map eventData = (Map) event.get("data");
4
5
System.out.println("Processing event: " + eventType);
6
7
switch (eventType) {
8
case "user.created":
9
// Handle new user registration
10
Map user = (Map