Integration Guides: Provider-specific integration guides overview and dashboard usage without individual provider details
---
# DOCUMENT BOUNDARY
---
# OpenAPI Specifications
> Access Scalekit OpenAPI specifications for API documentation and client generation
### [OpenAPI Spec](https://github.com/scalekit-inc/developer-docs/blob/main/public/api/scalekit.scalar.yaml) [YAMLv3.1.1](https://github.com/scalekit-inc/developer-docs/blob/main/public/api/scalekit.scalar.yaml) [Download the OpenAPI specification](https://github.com/scalekit-inc/developer-docs/blob/main/public/api/scalekit.scalar.yaml) ### [OpenAPI Spec](https://github.com/scalekit-inc/developer-docs/blob/main/public/api/scalekit.scalar.json) [JSONv3.1.1](https://github.com/scalekit-inc/developer-docs/blob/main/public/api/scalekit.scalar.json) [Download the OpenAPI specification](https://github.com/scalekit-inc/developer-docs/blob/main/public/api/scalekit.scalar.json)
---
# DOCUMENT BOUNDARY
---
# How to register a callback endpoint
> Learn how to register a callback endpoint in the Scalekit dashboard.
In the authentication flow for a user, a callback endpoint is the endpoint that Scalekit remembers about your application, trusts it, and sends a authentication grant (code). It further expects your application to exchange the code for a user token and user profile. This needs to be pre-registered in the Scalekit dashboard. Go to **Dashboard** > **Authentication** > **Redirect URLS** > **Allowed Callback URLs** and add the callback endpoint.  Your redirect URIs must meet specific requirements that vary between development and production environments: | Requirement | Development | Production | | ----------------- | ---------------------------- | -------------------- | | Supported schemes | `http` `https` `{scheme}` | `https` `{scheme}` | | Localhost support | Allowed | Not allowed | | Wildcard domains | Allowed | Not allowed | | URI length limit | 256 characters | 256 characters | | Query parameters | Not allowed | Not allowed | | URL fragments | Not allowed | Not allowed | Wildcards can simplify testing in development environments, but they must follow specific patterns: | Validation rule | Examples | | ------------------------------------------------ | -------------------------------------------------------------------- | | Wildcards cannot be used as root-level domains | `https://*.com``https://*.acmecorp.com``https://auth-*.acmecorp.com` | | Only one wildcard character is allowed per URI | `https://*.*.acmecorp.com``https://*.acmecorp.com` | | Wildcards must be in the hostname component only | `https://acmecorp.*.com``https://*.acmecorp.com` | | Wildcards must be in the outermost subdomain | `https://auth.*.acmecorp.com``https://*.auth.acmecorp.com` | Caution According to the [OAuth 2.0 specification](https://tools.ietf.org/html/rfc6749#section-3.1.2), redirect URIs must be absolute URIs. For development convenience, Scalekit relaxes this restriction slightly by allowing wildcards in development environments.
---
# DOCUMENT BOUNDARY
---
# View logs
> Monitor authentication activities and webhook deliveries using comprehensive logs that track user sign-ins, authentication methods, and webhook event processing.
Scalekit provides comprehensive logging for both authentication activities and webhook deliveries. Use these logs to monitor user access patterns, troubleshoot authentication issues, debug webhook integrations, and maintain compliance with audit requirements. ## Access logs [Section titled “Access logs”](#access-logs) **Authentication logs**: Navigate to **Dashboard > Auth Logs** to view all authentication events across your environment.  Each auth log entry displays the authentication event details, status, timestamp, user information, and authentication method used. **Webhook logs**: Navigate to **Dashboard > Webhooks** to view all configured webhook endpoints. Click on the specific webhook endpoint you want to monitor, then select the **”…”** (more options) button to access detailed delivery logs for that endpoint.  Each webhook log entry displays the webhook event details, delivery status, timestamp, and response information from your application. ## Authentication statuses [Section titled “Authentication statuses”](#authentication-statuses) Auth logs display four different statuses that help you understand where users are in the authentication flow: | Status | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Initiated** | The user has started the authentication process by accessing the `/oauth/authorize` endpoint. This indicates they’ve begun the authorization flow but haven’t completed it yet. | | **Pending** | The authentication is in a transitional state between initiation and completion. During this phase, the system performs redirects while exchanging user profile details for authorization code grants. The authentication is still in progress. | | **Success** | The system successfully exchanged the authorization code grant, verified the user’s identity, and granted them access. The authentication flow has completed successfully. | | **Failure** | The authentication process failed and access was denied. This could be due to invalid credentials, network issues, interceptor rejections, or other authentication failures. Review the error details to identify the cause of the failure. | ## Filter auth logs [Section titled “Filter auth logs”](#filter-auth-logs) When investigating incidents or troubleshooting issues, use filters to narrow down log data and quickly identify authentication problems. **Available filters:** * **Time range** - Filter logs by specific date and time periods to focus on recent activity or investigate historical events * **User email** - Search for authentication events from specific users to track individual user activity or troubleshoot sign-in issues * **Authentication status** - Filter by Initiated, Pending, Success, or Failure to isolate specific authentication outcomes * **Organization** - View authentication events for specific organizations in multi-tenant applications Combine multiple filters to narrow your search. For example, filter by a specific user email and Failure status to investigate why a user cannot sign in. ## Webhook logs [Section titled “Webhook logs”](#webhook-logs) ### Webhook delivery statuses [Section titled “Webhook delivery statuses”](#webhook-delivery-statuses) Webhook logs display four different statuses that indicate the delivery state of each webhook event: | Status | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Success** | Your application endpoint responded with a 2xx status code (typically 200 or 201), confirming successful receipt and processing of the webhook event. | | **Queued** | Due to high event volume or rate limiting, the webhook event is queued and waiting to be sent to your application endpoint. Events are processed in the order they were created. | | **Failed** | Your application endpoint did not respond, returned a non-2xx status code (typically 4xx or 5xx), or the request timed out. Failed deliveries trigger automatic retries. | | **Retrying** | Your application endpoint failed to acknowledge the webhook, and Scalekit is automatically retrying the delivery using exponential backoff. Retries continue up to 4 attempts with increasing delays between retries. | Monitor failed webhooks Failed webhooks can indicate issues with your endpoint availability, request validation, or processing logic. Review failed webhook logs to identify patterns and fix integration issues promptly. ### Filter webhook logs [Section titled “Filter webhook logs”](#filter-webhook-logs) When troubleshooting webhook delivery issues or investigating specific events, use filters to narrow down log data and quickly identify problems. **Available filters:** * **Time range** - Filter logs from the last 5 minutes to the last 30 days to focus on recent deliveries or investigate historical events * **Event type** - Filter by specific webhook event types (e.g., `organization.directory.user_created`, `organization.directory.user_updated`) to track particular types of events * **Delivery status** - Filter by Success, Queued, Failed, or Retrying to isolate problematic deliveries or verify successful processing Combine multiple filters to narrow your search. For example, filter by Failed status and a specific event type to investigate why certain events are not being processed successfully. ### Webhook log details [Section titled “Webhook log details”](#webhook-log-details) Click on any log entry to view detailed information about the webhook delivery: **Request details:** * Event ID and type * Timestamp when the event occurred * Request payload sent to your endpoint * Request headers including webhook signature **Response details:** * HTTP status code returned by your endpoint * Response body from your application * Response time and latency * Retry attempt number (if applicable) Use these details to debug webhook processing issues, verify signature validation, and ensure your endpoint handles events correctly. ### Retry behavior [Section titled “Retry behavior”](#retry-behavior) When webhook deliveries fail, Scalekit automatically retries sending the event to your endpoint: **Retry schedule:** * **Attempt 1**: Immediate delivery * **Attempt 2**: After 1 minute * **Attempt 3**: After 5 minutes * **Attempt 4**: After 15 minutes After the final retry attempt fails, the webhook is marked as permanently failed. You can view these failed webhooks in the logs and manually replay them when your endpoint is ready to process them.
---
# DOCUMENT BOUNDARY
---
# Custom email templates
> Customize authentication email templates with your branding and content
Scalekit uses default templates to send authentication emails to your users. You can customize these templates with your own branding and content to provide a consistent experience. Find these templates in **Emails** > **Templates**.  Select one of the listed templates and choose between Scalekit’s default templates or your own custom templates.  Select how each email is generated: * **Use Scalekit template**: Preview subject and bodies; you cannot edit them. Emails use Scalekit’s default content. * **Use custom template**: Edit the subject, HTML body, and plain text body. Your saved content is used for future sends. Requires you to [bring your own email provider](/guides/passwordless/custom-email-provider/). ## Provide HTML and plain text versions [Section titled “Provide HTML and plain text versions”](#provide-html-and-plain-text-versions) Provide both versions of your email body in the template editor. When both are present, Scalekit sends a multipart/alternative message: HTML is shown in capable clients, and the plain text part is used as a fallback where HTML is not supported. Once saved, all subsequent emails will use your customized templates. ## Built-in template variables [Section titled “Built-in template variables”](#built-in-template-variables) Use these built-in variables in your templates. Values are injected at send time. The variables below apply to all Scalekit templates. #### Application [Section titled “Application”](#application) Use application variables to include app-level data (for example, name, logo, support email) that stays the same across all emails for your app. | Variable | Description | | -------------------------------- | ------------------------------------------------ | | `{{app_name}}` | Your application name | | `{{app_logo_url}}` | Public URL to your application logo | | `{{app_support_email}}` | Support email address for your application | | `{{app_organization_meta_name}}` | Organization display name configured in Scalekit | #### Organization [Section titled “Organization”](#organization) Organization variables describe the organization that the user belongs to and are consistent across emails for that organization. | Variable | Description | | ----------------------- | --------------------- | | `{{organization_name}}` | The organization name | #### User [Section titled “User”](#user) User variables personalize the email for the recipient (for example, name and email). | Variable | Description | | ---------------- | ----------------------------- | | `{{user_name}}` | The recipient’s name | | `{{user_email}}` | The recipient’s email address | #### Contextual [Section titled “Contextual”](#contextual) Contextual variables apply only to the current template. They change per template or send (for example, OTP, magic link, or expiry). For example, `{{link}}` is maybe the same label in both sign up and log in scenarios using magic link. | Variable | Description | | -------------------------- | ----------------------------------------------------------------------------- | | `{{link}}` | Authentication link (magic link or sign up) | | `{{otp}}` | One-time passcode for the current request | | `{{expiry_time_relative}}` | Human-readable relative date format (for example, “14 days, 6 hours, 50 min”) | ## JET template syntax [Section titled “JET template syntax”](#jet-template-syntax) Custom email templates use JET (Just Enough Templates) syntax for dynamic content. JET provides powerful templating features including conditionals, loops, and filters. Here are two common patterns you can use in your email templates: * Conditional welcome message ```html {{ if user_name }} Hello {{ user_name }},
{{ else }} Hello,
{{ end }} Welcome to {{ app_name }}!
``` * User invite with organization ```html {{ if organization_name }} You have been invited to join {{ organization_name }} organization in {{ app_name }}.
{{ else }} You have been invited to {{ app_name }}.
{{ end }} ``` ## Inject you own variables at runtime Passwordless [Section titled “Inject you own variables at runtime ”](#inject-you-own-variables-at-runtime-) For more advanced personalization, you can use template variables to include values programatically in the emails. You must be using the Passwordless Headless API for authentication. * Each variable must be a key-value pair. * Maximum of 30 variables per template. * All template variables must have corresponding values in the request. * Avoid using reserved names: `otp`, `expiry_time_relative`, `link`, `expire_time`, `expiry_time`. 1. Create your email template with variables: Example email template ```html Hello {{ first_name }},
Welcome to {{ company_name }}.
Find your onboarding kit: {{ onboarding_resources }}
``` 2. Include variable values in your authentication request: Authentication request ```js const sendResponse = await scalekit.passwordless.sendPasswordlessEmail( "", { templateVariables: { first_name: "John", company_name: "Acme Corp", onboarding_resources: "https://acme.com/onboarding" } } ); ``` 3. The sent email will include the replaced values: Example email preview ```html Hello John, Welcome to Acme Corp. Find your onboarding kit: https://acme.com/onboarding ``` Caution The API will return a 400 status code if your template references any variables that aren’t provided in the request. *** **Test your knowledge with a quiz** Which choice requires using your own email provider? * Use Scalekit template * Preview subject and bodies * Use custom template * Enable table of contents Submit
---
# DOCUMENT BOUNDARY
---
# Configure initiate login endpoint
> Set up a login endpoint that Scalekit redirects to when users access your application through indirect entry points
In certain scenarios, Scalekit redirects users to your application’s login endpoint using OIDC third-party initiated login. Your application must implement this endpoint to construct the authorization URL and redirect users to Scalekit’s authentication flow. Scalekit redirects to your login endpoint in these (example) scenarios: * **Bookmarked login page**: Users bookmark your login page and visit it later. When they access the bookmarked URL, Scalekit redirects them to your application’s login endpoint because the original authentication transaction has expired. * **Password reset completion**: After users complete a password reset, Scalekit redirects them to your login endpoint. Users can then sign in with their new password. * **Email verification completion**: After users verify their email address during signup, Scalekit redirects them to your login endpoint to complete authentication. * **Organization invitations**: When users click an invitation link to join an organization, Scalekit redirects them to your login endpoint with invitation parameters. Your application must forward these parameters to Scalekit’s authorization endpoint. * **Disabled cookies**: If users navigate to Scalekit’s authorization endpoint with cookies disabled, Scalekit redirects them to your login endpoint. ## Configure the initiate login endpoint [Section titled “Configure the initiate login endpoint”](#configure-the-initiate-login-endpoint) Register your login endpoint in the Scalekit dashboard. Go to **Dashboard** > **Authentication** > **Redirect URLs** > **Initiate Login URL** and add your endpoint.  The endpoint must: * Use HTTPS (required in production) * Not point to localhost (production only) * Accept query parameters that Scalekit appends ## Implement the login endpoint [Section titled “Implement the login endpoint”](#implement-the-login-endpoint) Create a `/login` endpoint that constructs the authorization URL and redirects users to Scalekit. * Node.js routes/auth.js ```javascript 1 // Handle indirect auth entry points 2 app.get('/login', (req, res) => { 3 const redirectUri = 'http://localhost:3000/auth/callback'; 4 const options = { 5 scopes: ['openid', 'profile', 'email', 'offline_access'] 6 }; 7 8 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options); 9 res.redirect(authorizationUrl); 10 }); ``` * Python routes/auth.py ```python 1 from flask import redirect 2 from scalekit import AuthorizationUrlOptions 3 4 # Handle indirect auth entry points 5 @app.route('/login') 6 def login(): 7 redirect_uri = 'http://localhost:3000/auth/callback' 8 options = AuthorizationUrlOptions( 9 scopes=['openid', 'profile', 'email', 'offline_access'] 10 ) 11 12 authorization_url = scalekit_client.get_authorization_url(redirect_uri, options) 13 return redirect(authorization_url) ``` * Go routes/auth.go ```go 1 // Handle indirect auth entry points 2 r.GET("/login", func(c *gin.Context) { 3 redirectUri := "http://localhost:3000/auth/callback" 4 options := scalekitClient.AuthorizationUrlOptions{ 5 Scopes: []string{"openid", "profile", "email", "offline_access"} 6 } 7 8 authorizationUrl, _ := scalekitClient.GetAuthorizationUrl(redirectUri, options) 9 c.Redirect(http.StatusFound, authorizationUrl.String()) 10 }) ``` * Java AuthController.java ```java 1 import org.springframework.web.bind.annotation.GetMapping; 2 import org.springframework.web.bind.annotation.RestController; 3 import java.net.URL; 4 5 // Handle indirect auth entry points 6 @GetMapping("/login") 7 public String login() { 8 String redirectUri = "http://localhost:3000/auth/callback"; 9 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 10 options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); 11 12 URL authorizationUrl = scalekitClient.authentication().getAuthorizationUrl(redirectUri, options); 13 return "redirect:" + authorizationUrl.toString(); 14 } ```
---
# DOCUMENT BOUNDARY
---
# Redirects
> Learn how to configure and validate redirect URLs in Scalekit for secure authentication flows, including callback, login, logout, and back-channel logout endpoints
Redirects are registered endpoints in Scalekit that control where users are directed during authentication flows. You must configure these endpoints in the Scalekit dashboard before they can be used. All redirect URIs must be registered under Authentication settings in your Scalekit dashboard. This is a security requirement to prevent unauthorized redirects. ## Redirect endpoint types [Section titled “Redirect endpoint types”](#redirect-endpoint-types) ### Allowed callback URLs [Section titled “Allowed callback URLs”](#allowed-callback-urls) **Purpose**: Where users are sent after successful authentication to exchange authorization codes and retrieve profile information. **Example scenario**: A user completes sign-in and Scalekit redirects them to `https://yourapp.com/callback` where your application processes the authentication response. To add or remove an redirect URL, go to Dashboard > Authentication > Redirects > Allowed Callback URLs. ### Initiate login URL [Section titled “Initiate login URL”](#initiate-login-url) **Purpose**: When authentication does not initiate from your application, Scalekit redirects users back to your application’s login initiation endpoint. This endpoint should point to a route in your application that ultimately redirects users to Scalekit’s `/authorize` endpoint. **Example scenarios**: * **Bookmarked login page**: A user bookmarks your login page and visits it directly. Your application detects they’re not authenticated and redirects them to Scalekit’s authorization endpoint. * **Organization invitation flow**: A user clicks an invitation link to join an organization. Your application receives the invitation token and redirects the user to Scalekit’s authorization endpoint to complete the sign-up process. * **IdP-initiated SSO**: An administrator initiates single sign-on from their identity provider dashboard. The IdP redirects users to your application, which then redirects them to Scalekit’s authorization endpoint to complete authentication. * **Session expiration**: When a user’s session expires or they access a protected resource, they’re redirected to `https://yourapp.com/login` which then redirects to Scalekit’s authentication endpoint. ### Post logout URL [Section titled “Post logout URL”](#post-logout-url) **Purpose**: Where users are sent after successfully signing out of your application. **Example scenario**: After logging out, users are redirected to `https://yourapp.com/goodbye` to confirm their session has ended. ### Back channel logout URL [Section titled “Back channel logout URL”](#back-channel-logout-url) **Purpose**: A secure endpoint that receives notifications whenever a user is logged out from Scalekit, regardless of how the logout was initiated — admin triggered, user initiated, or due to session policies like idle timeout. **Example scenario**: When a user logs out from any application (user-initiated, admin-initiated, or due to session policies like idle timeout), Scalekit sends a logout notification to `https://yourapp.com/logout` to suggest termination of the user’s session across all connected applications, ensuring coordinated logout for enhanced security. ### Custom URI schemes [Section titled “Custom URI schemes”](#custom-uri-schemes) Custom URI schemes allow for redirects, enabling deep linking and native app integrations. Some applications include: * **Desktop applications**: Use schemes like `{scheme}://` for native app integration * **Mobile apps**: Use schemes like `myapp://` for mobile app deep linking **Example custom schemes**: * `{scheme}://auth/callback` - For custom scheme authentication * `myapp://login/callback` - For mobile app authentication ## URI validation requirements [Section titled “URI validation requirements”](#uri-validation-requirements) Your redirect URIs must meet specific requirements that vary between development and production environments: | Requirement | Development | Production | | ----------------- | ---------------------------- | -------------------- | | Supported schemes | `http` `https` `{scheme}` | `https` `{scheme}` | | Localhost support | Allowed | Not allowed | | Wildcard domains | Allowed | Not allowed | | URI length limit | 256 characters | 256 characters | | Query parameters | Not allowed | Not allowed | | URL fragments | Not allowed | Not allowed | ### Wildcard usage patterns [Section titled “Wildcard usage patterns”](#wildcard-usage-patterns) Wildcards can simplify testing in development environments, but they must follow specific patterns: | Validation rule | Examples | | ------------------------------------------------ | -------------------------------------------------------------------- | | Wildcards cannot be used as root-level domains | `https://*.com``https://*.acmecorp.com``https://auth-*.acmecorp.com` | | Only one wildcard character is allowed per URI | `https://*.*.acmecorp.com``https://*.acmecorp.com` | | Wildcards must be in the hostname component only | `https://acmecorp.*.com``https://*.acmecorp.com` | | Wildcards must be in the outermost subdomain | `https://auth.*.acmecorp.com``https://*.auth.acmecorp.com` | Caution According to the [OAuth 2.0 specification](https://tools.ietf.org/html/rfc6749#section-3.1.2), redirect URIs must be absolute URIs. For development convenience, Scalekit relaxes this restriction slightly by allowing wildcards in development environments.