Headless email API for magic link and OTP

Implement email OTP or magic link using direct API calls with full control over UX

Implement magic link and OTP authentication using Scalekit’s headless APIs. Send either a one-time passcode (OTP) or a magic link to the user’s email, then verify their identity. Magic link and OTP offer two email-based authentication methods, clickable links or one-time passcodes, so users can sign in without passwords. You control the UI and user flows, while Scalekit provides the backend authentication infrastructure.

See the integration in action

Review the authentication sequence

Coming soon

Using a coding agent?

Set up Scalekit
Section titled “Set up Scalekit”

Install the Scalekit SDK to your project.
npm install @scalekit-sdk/node
pip install scalekit-sdk-python
go get -u github.com/scalekit-inc/scalekit-sdk-go
/* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.1.3"
 <dependency> <groupId>com.scalekit</groupId> <artifactId>scalekit-sdk-java</artifactId> <version>2.1.3</version> </dependency>
Your application is responsible for verifying users and initiating sessions, while Scalekit securely manages authentication tokens to ensure the verification process is completed successfully
Configure magic link and OTP settings
Section titled “Configure magic link and OTP settings”

In the Scalekit dashboard, enable magic link and OTP and choose your login method.

Optional security settings:
- Enforce same-browser origin: Users must complete magic-link auth in the same browser they started in.
- Issue new credentials on resend: Each resend generates a fresh code or link and invalidates the previous one.

Send verification email

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

Follow these steps to implement the verification email flow:

Create a form to collect the user’s email address
Call the passwordless API (magic link and OTP) when the form is submitted
Handle the response to provide feedback to the user

POST /api/v1/passwordless/email/send

Example implementation

1
  curl -L '<SCALEKIT_ENVIRONMENT_URL>/api/v1/passwordless/email/send' \
2
  -H 'Content-Type: application/json' \
3
  -H 'Authorization: Bearer eyJh..' \
4
  --data-raw '{
5
      "email": "john.doe@example.com",
6
      "expires_in": 300,
7
      "state": "jAy-state1-gM4fdZ...2nqm6Q",
8
      "template": "SIGNIN",
9

10
      "magiclink_auth_uri": "https://yourapp.com/passwordless/verify",
11
      "template_variables": {
12
        "custom_variable_key": "custom_variable_value"
13
      }
14
  }'
15

16
# Response
6 collapsed lines
17
# {
18
# "auth_request_id": "jAy-state1-gM4fdZ...2nqm6Q"
19
# "expires_at": "1748696575"
20
# "expires_in": 100
21
# "passwordless_type": "OTP" | "LINK" | "LINK_OTP"
22
# }

Request parameters

Parameter	Required	Description
`email`	Yes	Recipient’s email address string
`expires_in`	No	Code expiration time in seconds (default: 300) number
`state`	No	OIDC state parameter for request validation string
`template`	No	Email template to use (`SIGNIN` or `SIGNUP`) string
`magiclink_auth_uri`	No	Magic 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 your authentication method.string
`template_variables`	No	Pass variables to be used in the email template sent to the user. You may include up to 30 key-value pairs to reference in the email template. object

Response parameters

Parameters	Description
`auth_request_id`	A unique identifier for the authentication request that can be used to verify the code string
`expires_at`	Unix timestamp indicating when the verification code will expire string
`expires_in`	The time in seconds after which the verification code will expire. Default is 100 seconds number
`passwordless_type`	The type of magic link and OTP authentication. Currently supports `OTP`, `LINK` and `LINK_OTP` string

1
const options = {
2
  template: "SIGNIN",
3
  state: "jAy-state1-...2nqm6Q",
4
  expiresIn: 300,
5
  // Required if you selected Link or Link+OTP as your authentication method
6
  magiclinkAuthUri: "https://yourapp.com/passwordless/verify",
7
    templateVariables: {
8
        employeeID: "EMP523",
9
        teamName: "Alpha Team",
10
    },
11
};
12

13
const sendResponse = await scalekit.passwordless
14
  .sendPasswordlessEmail(
15
    "<john.doe@example.com>",
16
    options
17
);
18

19
// sendResponse = {
20
//   authRequestId: string,
21
//   expiresAt: number,    // seconds since epoch
22
//   expiresIn: number,    // seconds
23
//   passwordlessType: string  // "OTP" | "LINK" | "LINK_OTP"
24
// }

Request parameters

Parameter	Required	Description
`email`	Yes	The email address to send the magic link or OTP verification code to string
`template`	No	The template type (`SIGNIN`/`SIGNUP`) string
`state`	No	Optional state parameter to maintain state between request and callback string
`expiresIn`	No	Optional expiration time in seconds (default: 300) number
`magiclinkAuthUri`	No	Magic 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 your authentication method.string
`template_variables`	No	Pass variables to be used in the email template sent to the user. You may include up to 30 key-value pairs to reference in the email template. object

Response parameters

Parameters	Description
`authRequestId`	Unique identifier for the magic link and OTP authentication request string
`expiresAt`	Expiration time in seconds since epoch number
`expiresIn`	Expiration time in seconds number
`passwordlessType`	Type of magic link and OTP authentication (`OTP`, `LINK` or `LINK_OTP`) string

1
response = client.passwordless.send_passwordless_email(
2
    email="john.doe@example.com",
3
    template="SIGNIN",  # or "SIGNUP", "UNSPECIFIED"
4
    expires_in=300,
5
    magiclink_auth_uri="https://yourapp.com/passwordless/verify",
6
    template_variables={
7
        "employeeID": "EMP523",
8
        "teamName": "Alpha Team",
9
    },
10
)
11

12
# Extract auth request ID from response
13
auth_request_id = response[0].auth_request_id

1
// Send a passwordless email (assumes you have an initialized `client` and `ctx`)
2
templateType := scalekit.TemplateTypeSignin
3
resp, err := scalekitClient.Passwordless().SendPasswordlessEmail(
4
  ctx,
5
  "john.doe@example.com",
6
  &scalekit.SendPasswordlessOptions{
7
    Template:          &templateType,
8
    State:             "jAy-state1-gM4fdZ...2nqm6Q",
9
    ExpiresIn:         300,
10
    MagiclinkAuthUri:  "https://yourapp.com/passwordless/verify", // required if Link or Link+OTP
11
    TemplateVariables: map[string]string{
12
      "employeeID": "EMP523",
13
      "teamName": "Alpha Team",
14
    },
15
  },
16
)
17

18
// resp contains: AuthRequestId, ExpiresAt, ExpiresIn, PasswordlessType

Request parameters

Parameter	Required	Description
`email`	Yes	The email address to send the magic link or OTP verification code to string
`MagiclinkAuthUri`	No	Magic Link URI for authentication string
`State`	No	Optional state parameter string
`Template`	No	Email template type (`SIGNIN`/`SIGNUP`) string
`ExpiresIn`	No	Expiration time in seconds number
`TemplateVariables`	No	Key-value pairs for email template object

Response parameters

Parameters	Description
`AuthRequestId`	Unique identifier for the magic link and OTP authentication request string
`ExpiresAt`	Expiration time in seconds since epoch number
`ExpiresIn`	Expiration time in seconds number
`PasswordlessType`	Type of magic link and OTP authentication (`OTP`, `LINK` or `LINK_OTP`) string

1
import java.util.HashMap;
2
import java.util.Map;
3

4
TemplateType templateType = TemplateType.SIGNIN;
5
Map<String, String> templateVariables = new HashMap<>();
6
templateVariables.put("employeeID", "EMP523");
7
templateVariables.put("teamName", "Alpha Team");
8

9
SendPasswordlessOptions options = new SendPasswordlessOptions();
10
options.setTemplate(templateType);
11
options.setExpiresIn(300);
12
options.setMagiclinkAuthUri("https://yourapp.com/passwordless/verify");
13
options.setTemplateVariables(templateVariables);
14

15
SendPasswordlessResponse response = passwordlessClient.sendPasswordlessEmail(
16
    "john.doe@example.com",
17
    options
18
);
19

20
String authRequestId = response.getAuthRequestId();

Resend a verification email

Users can request a new verification email if they need one. Use the following endpoint to resend an OTP or magic link email.

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

8
# Response
9

10
# {
11

12
# "auth_request_id": "jAy-state1-gM4fdZ...2nqm6Q"
13

14
# "expires_at": "1748696575"
15

16
# "expires_in": 300
17

18
# "passwordless_type": "OTP" | "LINK" | "LINK_OTP"
19

20
# }

Request parameters

Parameters	Required	Description
`auth_request_id`	Yes	The unique identifier for the authentication request that was sent earlier string

Response parameters

Parameters	Description
`auth_request_id`	A unique identifier for the authentication request that can be used to verify the code string
`expires_at`	Unix timestamp indicating when the verification code will expire string
`expires_in`	The time in seconds after which the verification code will expire. Default is 300 seconds number
`passwordless_type`	The type of magic link and OTP authentication. Currently supports `OTP`, `LINK` and `LINK_OTP` string

1
const { authRequestId } = sendResponse;
2
const resendResponse = await scalekit.passwordless
3
.resendPasswordlessEmail(
4
    authRequestId
5
);
6

7
// resendResponse = {
8
//   authRequestId: "jAy-state1-gM4fdZ...2nqm6Q",
9
//   expiresAt: "1748696575",
10
//   expiresIn: "300",
11
//   passwordlessType: "OTP" | "LINK" | "LINK_OTP"
12
// }

Request parameters

Parameters	Required	Description
`authRequestId`	Yes	The unique identifier for the authentication request that was sent earlier string

Response parameters

Parameters	Description
`authRequestId`	Unique identifier for the magic link and OTP authentication request string
`expiresAt`	Expiration time in seconds since epoch number
`expiresIn`	Expiration time in seconds. Default is 300 seconds number
`passwordlessType`	`OTP`, `LINK` or `LINK_OTP` string

1
resend_response = client.passwordless.resend_passwordless_email(
2
    auth_request_id=auth_request_id,
3
)
4

5
new_auth_request_id = resend_response[0].auth_request_id

1
// Resend passwordless email for an existing auth request
2
resendResp, err := scalekitClient.Passwordless().ResendPasswordlessEmail(
3
  ctx,            // context.Context (e.g., context.Background())
4
  authRequestId,  // string: from the send email response
5
)
6

7
if err != nil {
8
  // handle error (log, return HTTP 400/500, etc.)
9
  // ...
10
}
11

12
// resendResp is a pointer to ResendPasswordlessResponse struct:
13
// type ResendPasswordlessResponse struct {
14
//   AuthRequestId    string // Unique ID for the passwordless request
15
//   ExpiresAt        int64  // Unix timestamp (seconds since epoch)
16
//   ExpiresIn        int    // Expiry duration in seconds
17
//   PasswordlessType string // "OTP", "LINK", or "LINK_OTP"
18
// }

Request parameters

Parameters	Required	Description
`authRequestId`	Yes	The unique identifier for the authentication request that was sent earlier string

Response parameters

Parameters	Description
`AuthRequestId`	Unique identifier for the magic link and OTP authentication request string
`ExpiresAt`	Expiration time in seconds since epoch number
`ExpiresIn`	Expiration time in seconds. Default is 300 seconds number
`PasswordlessType`	`OTP`, `LINK` or `LINK_OTP` string

SendPasswordlessResponse resendResponse = passwordlessClient.resendPasswordlessEmail(authRequestId);

If you enabled Enable new Magic link & OTP credentials on resend in the Scalekit dashboard, a new verification code or magic link will be sent each time the user requests a new one.

Verify the user’s identity

Once the user receives the verification email,

If it is a verification code, they’ll enter it in your application. Use the following endpoint to validate the code and complete authentication.
If it is a magic link, they’ll click the link in the email to verify their address. Capture the link_token query parameter and use it to verify.
For additional security with magic links, if you enabled “Enforce same browser origin” in the dashboard, include the auth_request_id in the verification request.

Verification code
Magic link verification

Create a form to collect the verification code
Call the verification API when the form is submitted to verify the code
Handle the response to either grant access or show an error

POST /api/v1/passwordless/email/verify

Example implementation

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

Parameters	Required	Description
`code`	Yes	The verification code entered by the user string
`auth_request_id`	Yes	The request ID from the response when the verification email was sent string

Response parameters

Parameters	Description
`email`	The email address of the user string
`state`	The state parameter that was passed in the original request string
`template`	The template that was used for the verification code string
`passwordless_type`	The type of magic link and OTP authentication. Currently supports `OTP`, `LINK` and `LINK_OTP` string

1
const { authRequestId } = sendResponse;
2
const verifyResponse = await scalekit.passwordless
3
  .verifyPasswordlessEmail(
4
    { code: "123456"},
5
    authRequestId
6
  );
7

8
// verifyResponse = {
9
//   "email": "saifshine7@gmail.com",
10
//   "state": "jAy-state1-gM4fdZdV22nqm6Q_j..",
11
//   "template": "SIGNIN",
12
//   "passwordless_type": "OTP" | "LINK" | "LINK_OTP"
13
// }

Request parameters

Parameters	Required	Description
`options.code`	Yes	The verification code received by the user string
`authRequestId`	Yes	The unique identifier for the authentication request that was sent earlier string

Response parameters

Parameters	Description
`email`	The email address of the user string
`state`	The state parameter that was passed in the original request string
`template`	The template that was used for the verification code string
`passwordlessType`	The type of magic link and OTP authentication. Currently supports `OTP`, `LINK` and `LINK_OTP` string

1
verify_response = client.passwordless.verify_passwordless_email(
2
    code="123456",  # OTP code received via email
3
    auth_request_id=auth_request_id,
4
)
5

6
# User verified successfully
7
user_email = verify_response[0].email

1
// Verify with OTP code
2
verifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail(
3
    ctx,
4
    &scalekit.VerifyPasswordlessOptions{
5
        Code:          "123456", // OTP code
6
        AuthRequestId: authRequestId,
7
    },
8
)
9

10
if err != nil {
11
    // Handle error
12
    return
13
}
14

15
// verifyResp contains the verified user's info
16
// type VerifyPasswordLessResponse struct {
17
//   Email            string
18
//   State            string
19
//   Template         string // SIGNIN | SIGNUP
20
//   PasswordlessType string // OTP | LINK | LINK_OTP
21
// }

Request parameters

Parameters	Required	Description
`options.Code`	Yes	The verification code received by the user string
`options.AuthRequestId`	Yes	The unique identifier for the authentication request that was sent earlier string

Response parameters

Parameters	Description
`Email`	The email address of the user string
`State`	The state parameter that was passed in the original request string
`Template`	The template that was used (`SIGNIN` or `SIGNUP`) string
`PasswordlessType`	`OTP`, `LINK` or `LINK_OTP` string

1
// Verify with OTP code
2
VerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions();
3
verifyOptions.setCode("123456"); // OTP code
4
verifyOptions.setAuthRequestId(authRequestId);
5

6
VerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions);
7

8
// User verified successfully
9
String userEmail = verifyResponse.getEmail();

To support magic link verification, add a callback endpoint in your application typically at https://your-app.com/passwordless/verify. Implement it to verify the magic link token and complete the user authentication process.

Create a verification endpoint in your application to handle the magic link verification. This is the endpoint that the user lands in when they click the link in the email.
Capture the magic link token from the link_token request parameter from the URL.
Call the verification API when the user clicks the link in the email.
Based on token verification, complete the authentication process or show an error with an appropriate error message.

POST /api/v1/passwordless/email/verify

Example implementation

curl -L '<SCALEKIT_ENVIRONMENT_URL>/api/v1/passwordless/email/verify' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsIm..' \
-d '{
    "link_token": "a4143d8f-...c846ed91e_l",
    "auth_request_id": "YC4QR-dVZVtNNVHcHwrnHNDV..." // (optional)
}'

Request parameters

Parameters	Required	Description
`link_token`	Yes	The link token received by the user string
`auth_request_id`	No	The request ID you received when the verification email was sent. string

Response parameters

Parameters	Description
`email`	The email address of the user string
`state`	The state parameter that was passed in the original request string
`template`	The template that was used for the verification code string
`passwordless_type`	The type of magic link and OTP authentication. Currently supports `OTP`, `LINK` and `LINK_OTP` string

1
// User clicks the magic link in their email
2
// Example magic link: https://yourapp.com/passwordless/verify?link_token=a4143d8f-d13d-415c-8f5a-5a5c846ed91e_l
3

4
// 2. Express endpoint to handle the magic link verification
5
app.get('/passwordless/verify', async (req, res) => {
6
  const { link_token } = req.query;
7

8
  try {
9
    // 3. Verify the magic link token with Scalekit
10
    const verifyResponse = await scalekit.passwordless
11
      .verifyPasswordlessEmail(
12
        { linkToken: link_token },
13
        authRequestId // (optional) sendResponse.authRequestId
14
      );
7 collapsed lines
15

16
    // 4. Successfully log the user in
17
    // Set session/token and redirect to dashboard
18
    res.redirect('/dashboard');
19
  } catch (error) {
20
    res.status(400).json({
21
         error: 'The magic link is invalid or has expired. Please request a new verification link.'
22
     });
23
  }
24
});
25

26
// verifyResponse = {
27
//   "email": "saifshine7@gmail.com",
28
//   "state": "jAy-state1-gM4fdZdV22nqm6Q_j..",
29
//   "template": "SIGNIN",
30
//   "passwordless_type": "OTP" | "LINK" | "LINK_OTP"
31
// }

Request parameters

Parameters	Required	Description
`options.linkToken`	Yes	The link token received by the user string
`authRequestId`	No	The unique identifier for the authentication request that was sent earlier. string

Response parameters

Parameters	Description
`email`	The email address of the user string
`state`	The state parameter that was passed in the original request string
`template`	The template that was used for the verification code string
`passwordlessType`	The type of magic link and OTP authentication. Currently supports `OTP`, `LINK` and `LINK_OTP` string

1
# Verify with magic link token
2
verify_response = client.passwordless.verify_passwordless_email(
3
    link_token=link_token,  # Magic link token from URL
4
    # auth_request_id=auth_request_id,  # optional if same-origin enforcement enabled
5
)
6

7
# User verified successfully
8
user_email = verify_response[0].email

1
verifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail(
2
    ctx,
3
    &scalekit.VerifyPasswordlessOptions{
4
        LinkToken: linkToken, // Magic link token
5
    },
6
)
7

8
if err != nil {
9
    // Handle error
10
    return
11
}
12

13
// User verified successfully
14
userEmail := verifyResponse.Email

1
// Verify with magic link token
2
VerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions();
3
verifyOptions.setLinkToken(linkToken); // Magic link token
4
// verifyOptions.setAuthRequestId(authRequestId); // optional if same-origin enforcement enabled
5

6
VerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions);
7

8
// User verified successfully
9
String userEmail = verifyResponse.getEmail();

You’ve successfully implemented Magic link & OTP authentication in your application. Users can now sign in securely without passwords by entering a verification code (OTP) or clicking a magic link sent to their email.

Headless email API for magic link and OTP

Set up Scalekit

Configure magic link and OTP settings

Send verification email

Resend a verification email

Verify the user’s identity