Passwordless quickstart (via OIDC)

This guide will walk you through implementing passwordless authentication via Scalekit’s OIDC flow. Depending on your configuration, your users will be sent either a one time passcode (OTP) or a magic link to verify their identity.

Prerequisites

Before you begin, ensure you have:

1. Access to your Scalekit Account and the API credentials. If you don’t have a Scalekit account yet, you can signup here.

2. Installed Scalekit SDK into your project

   npm install @scalekit/sdk

   import { Scalekit } from '@scalekit-sdk/node';
   
   const scalekit = new Scalekit(
     '<SCALEKIT_ENVIRONMENT_URL>',
     '<SCALEKIT_CLIENT_ID>',
     '<SCALEKIT_CLIENT_SECRET>',
   );

Implementation guide

1. Configure settings

   Before implementing the code, ensure passwordless authentication is properly configured in your Scalekit dashboard:

   1. Navigate to Authentication > Auth Methods
   2. Locate the Passwordless section
   3. Choose the type of passwordless authentication to use.
   4. Save your changes

   

2. Initiate authorize request

   To initiate passwordless authentication, redirect users to the Scalekit authorization endpoint with the appropriate parameters.

   Construct your authorization URL with the following parameters and redirect the user to the authorization URL.

   Parameter	Description
   redirect_uri	Your application endpoint that will receive the authorization code after successful authentication. Example: https://your-app.com/auth/callback
   client_id	Your unique Scalekit application identifier that specifies both your app and environment (staging, production).
   login_hint	The email address of the user to send the verification email

   Example implementation

   Node.js

   import { ScalekitClient } from '@scalekit-sdk/node';
   // Initialize the SDK client
   const scalekit = new ScalekitClient(
     '<SCALEKIT_ENVIRONMENT_URL>',
     '<SCALEKIT_CLIENT_ID>',
     '<SCALEKIT_CLIENT_SECRET>',
   );
   
   const options = {};
   
   options['loginHint'] = 'user@example.com';
   
   const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options);

   Python

   from scalekit import ScalekitClient, AuthorizationUrlOptions, CodeAuthenticationOptions
   
   # Initialize the SDK client
   scalekit = ScalekitClient(
     '<SCALEKIT_ENVIRONMENT_URL>',
     '<SCALEKIT_CLIENT_ID>',
     '<SCALEKIT_CLIENT_SECRET>'
   )
   
   options = AuthorizationUrlOptions()
   
   # Authorization URL with login hint
   options.login_hint = 'user@example.com'
   
   authorization_url = scalekit_client.get_authorization_url(
     redirect_uri=<redirect_uri>,
     options=options
   )
   
   # Redirect the user to this authorization URL

   Go

   import (
     "github.com/scalekit/scalekit-sdk-go"
   )
   
   func main() {
     // Initialize the SDK client
     scalekitClient := scalekit.NewScalekitClient(
       "<SCALEKIT_ENVIRONMENT_URL>",
       "<SCALEKIT_CLIENT_ID>",
       "<SCALEKIT_CLIENT_SECRET>"
     )
   
     options := scalekitClient.AuthorizationUrlOptions{}
     // User's email domain detects the correct enterprise SSO connection.
     options.LoginHint = "user@example.com"
   
     authorizationURL := scalekitClient.GetAuthorizationUrl(
       redirectUrl,
       options,
     )
     // Next step is to redirect the user to this authorization URL
   }
   
   // Redirect the user to this authorization URL

   Java

   package com.scalekit;
   
   import com.scalekit.ScalekitClient;
   import com.scalekit.internal.http.AuthorizationUrlOptions;
   
   public class Main {
   
     public static void main(String[] args) {
       // Initialize the SDK client
       ScalekitClient scalekitClient = new ScalekitClient(
         "<SCALEKIT_ENVIRONMENT_URL>",
         "<SCALEKIT_CLIENT_ID>",
         "<SCALEKIT_CLIENT_SECRET>"
       );
       AuthorizationUrlOptions options = new AuthorizationUrlOptions();
       // User's email domain detects the correct enterprise SSO connection.
       options.setLoginHint("user@example.com");
       try {
         String url = scalekitClient
           .authentication()
           .getAuthorizationUrl(redirectUrl, options)
           .toString();
       } catch (Exception e) {
         System.out.println(e.getMessage());
       }
     }
   }
   // Redirect the user to this authorization URL

   This redirect will send users to the Scalekit authentication flow, where they’ll authenticate with their email before being returned to your application.

   Example authorization URL

   <YOURAPP_SCALEKIT_ENVIRONMENT_URL>/authorize?
     client_id=skc_122056050118122349527&
     redirect_uri=https://yourapp.com/auth/callback&
     login_hint=user@example.com&
     response_type=code&
     scope=openid%20profile%20email&
     state=jAy-state1-gM4fdZdV22nqm6Q_jAy-XwpYdYFh..2nqm6Q

   After redirecting users to the Scalekit authorization endpoint, handle the callback at your redirect_uri to retrieve the user profile and complete the authentication process.

3. Fetch user details

   After successful user authentication via OTP, Scalekit redirects users to your specified redirect_uri with a temporary authorization code parameter. This code must be exchanged for the user’s profile information through a secure server-side request.

   The authorization code exchange process should always be performed server-side to maintain security. This server-side request will:

   1. Validate the authorization code
   2. Return the authenticated user’s profile details
   Node.js

   Fetch user profile

   // Handle oauth redirect_url, fetch code and error_description from request params
   const { code, error, error_description } = req.query;
   
   if (error) {
     // Handle errors
   }
   
   const result = await scalekit.authenticateWithCode(code, redirectUri);
   const userEmail = result.user.email;
   
   // Next step: create a session for this user and allow access

   Python

   Fetch user profile

   # Handle oauth redirect_url, fetch code and error_description from request params
   code = request.args.get('code')
   error = request.args.get('error')
   error_description = request.args.get('error_description')
   
   if error:
       raise Exception(error_description)
   
   result = scalekit.authenticate_with_code(code, '<redirect_uri>')
   
   # result.user has the authenticated user's details
   user_email = result.user.email
   
   # Next step: create a session for this user and allow access

   Go

   Fetch user profile

   // Handle oauth redirect_url, fetch code and error_description from request params
   code: = r.URL.Query().Get("code")
   error: = r.URL.Query().Get("error")
   errorDescription: = r.URL.Query().Get("error_description")
   
   if error != "" {
     // Handle errors
   }
   
   result, err: = a.scalekit.AuthenticateWithCode(code,<redirectUrl>)
   
   if err != nil {
     // Handle errors
   }
   
   // result.User has the authenticated user's details
   userEmail: = result.User.Email
   
   // Next step: create a session for this user and allow access

   Java

   Fetch user profile

   // Handle oauth redirect_url, fetch code and error_description from request params
   String code = request.getParameter("code");
   String error = request.getParameter("error");
   String errorDescription = request.getParameter("error_description");
   
   if (error != null && !error.isEmpty()) {
       // Handle errors
       return;
   }
   
   try {
       AuthenticationResponse result = scalekit.authentication().authenticateWithCode(code, redirectUrl);
       String userEmail = result.getIdTokenClaims().getEmail();
   
       // Next step: create a session for this user and allow access
   } catch (Exception e) {
       // Handle errors
   }

   The result object

   Result object

   {
     user: {
       email: "john.doe@example.com"  // User's email address
     },
     idToken: "<USER_PROFILE_JWT>",   // JWT containing user profile information
     accessToken: "<API_CALL_JWT>",   // Temporary Access Token for accessing user's email
     expiresIn: 899                    // Token expiration time in seconds
   }

Congratulations! You’ve successfully implemented passwordless authentication in your application. Users can now sign in securely without passwords by entering a verification code or clicking a magic link sent to their email.

Next steps

• Bring your own email provider Coming soon
• Customize the email templates to match your brand Coming soon

Need more help? Reach out to us for any questions or support