Skip to content
Scalekit Docs

Passwordless quickstart

This guide explains how you can implement passwordless authentication using Scalekit’s APIs to send either verification codes or magic links to your user’s email address and verify their identity.

Prerequisites

Section titled “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

    Terminal window
    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

Section titled “Implementation guide”

  1. Configure settings

    Section titled “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. Send verification email

    Section titled “Send verification email”

    The first step in the passwordless flow is to send a verification email to the user’s email. This verification email contains either a one-time passcode or a magic link or both based on your selection in the Scalekit dashboard (earlier step).

    Follow these steps to implement the verification email flow:

    1. Create a form to collect the user’s email address
    2. Call the passwordless API when the form is submitted
    3. Handle the response to provide feedback to the user
    API endpoint
    POST /api/v1/passwordless/email/send

    Example implementation

    Request
    # Send a passwordless verification code to user's email
    curl -L '<SCALEKIT_ENVIRONMENT_URL>/api/v1/passwordless/email/send' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJh..' \
    --data-raw '{
        "email": "john.doe@example.com",
        "expires_in": 3600,
        "state": "jAy-state1-gM4fdZ...2nqm6Q",
        "template": "SIGNIN",
    

        "magiclink_auth_uri": "https://yourapp.com/passwordless/verify"
    }'
    

    # Response
    # {
    #  "auth_request_id": "jAy-state1-gM4fdZ...2nqm6Q"
    #  "expires_at": "1748696575"
    #  "expires_in": 100
    #  "passwordless_type": "OTP" | "LINK" | "LINK_OTP"
    # }
    Request parameters
    ParameterRequiredDescription
    emailYesRecipient’s email address string
    expires_inNoCode expiration time in seconds (default: 300) number
    stateNoOIDC state parameter for request validation string
    templateNoEmail template to use (SIGNIN or SIGNUP) string
    magiclink_auth_uriNoMagic Link URI that will be sent to your user to complete the authentication flow. If the URL is of the format https://yourapp.com/passwordless/verify, the magic link sent to your user via email will be https://yourapp.com/passwordless/verify?link_token=<link_token>. Required if you selected Link or Link + OTP as the passwordless option.string
    Response parameters
    ParametersDescription
    auth_request_idA unique identifier for the authentication request that can be used to verify the code string
    expires_atUnix timestamp indicating when the verification code will expire string
    expires_inThe time in seconds after which the verification code will expire. Default is 100 seconds number
    passwordless_typeThe type of passwordless authentication to use. Currently supports OTP, LINK and LINK_OTP string

  3. Resend a verification email

    Section titled “Resend a verification email”

    Users can request a new verification email if they need one. Use the following endpoint to send a fresh email to verify using OTP or Magic Link.

    Request
    curl -L '<SCALEKIT_ENVIRONMENT_URL>/api/v1/passwordless/email/resend' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsIm..' \
    -d '{
        "auth_request_id": "jAy-state1-gM4fdZ...2nqm6Q"
    }'
    

    # Response
    # {
    # "auth_request_id": "jAy-state1-gM4fdZ...2nqm6Q"
    # "expires_at": "1748696575"
    # "expires_in": 3600
    # "passwordless_type": "OTP" | "LINK" | "LINK_OTP"
    # }
    Request parameters
    ParametersRequiredDescription
    auth_request_idYesThe unique identifier for the authentication request that was sent earlier string
    Response parameters
    ParametersDescription
    auth_request_idA unique identifier for the authentication request that can be used to verify the code string
    expires_atUnix timestamp indicating when the verification code will expire string
    expires_inThe time in seconds after which the verification code will expire. Default is 3600 seconds number
    passwordless_typeThe type of passwordless authentication to use. Currently supports OTP, LINK and LINK_OTP string

  4. Verify the user’s identity

    Section titled “Verify the user’s identity”

    Once the user receives the verification email,

    • If it’s Verification code, they’ll enter it in your application. Use the following endpoint to validate the code and complete the authentication process.
    • If it’s Magic Link, they’ll click the link in the email to verify their email address. Capture the link_token request parameter from the URL and use it to verify the user’s email address.
    • For additional security with magic links, if you enabled the option “Enforce same browser origin”, you are required to send the auth_request_id to the verification endpoint.
    1. Create a form to collect the verification code
    2. Call the verification API when the form is submitted to verify the code
    3. Handle the response to either grant access or show an error
    API endpoint
    POST /api/v1/passwordless/email/verify

    Example implementation

    Request
    curl -L '<SCALEKIT_ENVIRONMENT_URL>/api/v1/passwordless/email/verify' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsIm..' \
    -d '{
        "code": "123456",
        "auth_request_id": "YC4QR-dVZVtNNVHcHwrnHNDV..."
    }'
    Request parameters
    ParametersRequiredDescription
    codeYesThe verification code entered by the user string
    auth_request_idYesThe request ID from the response when the verification email was sent string
    Response parameters
    ParametersDescription
    emailThe email address of the user string
    stateThe state parameter that was passed in the original request string
    templateThe template that was used for the verification code string
    passwordless_typeThe type of passwordless authentication to use. Currently supports OTP, LINK and LINK_OTP string

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

Section titled “Next steps”
  • Test your implementation: Try the complete authentication flow to ensure everything works as expected
  • Enhance security: Consider implementing rate limiting and suspicious activity monitoring
  • Customize emails: Update the email templates to match your brand Coming soon
Need more help? Reach out to us for any questions or support