Skip to main content

Passwordless Sign-In Integration Guide

Overview​

This guide provides a comprehensive step-by-step process for integrating passwordless sign-in using the login_url API. This integration allows users to authenticate seamlessly into the account portal using a single set of credentials, reducing friction and enhancing security 🚀.

By following these steps, you will:

  • Verify whether a user exists in your system
  • Create a new user if they are not found
  • Update user details to ensure accurate records
  • Generate a passwordless login link for one-click authentication

This guide is designed for developers implementing passwordless sign-in in their applications using our API. Before you begin, ensure you have the necessary API credentials and access rights.

Note: You must have a valid API key for authentication before proceeding. Include this key in the headers of all API calls.

Step 1: Verify User Details​

The first step is verifying whether a user already exists in your system. This verification is crucial because:

  • If the user exists, you can proceed with updating their details or generating a passwordless login link
  • If the user does not exist, you will need to create a new user account

Start by filtering users by email or business ID to retrieve a list of users.

  • Filtering by Email: Pass the user's email as a query parameter to retrieve a specific user
  • Filtering by Business ID: Filter users by their associated business ID since all users belong to a business entity

Example Request:

curl -X GET "https://<api-host>/users?email=user@example.com&type=BUSINESS" \
     -H "x-api-key: <YOUR_API_KEY>"

To check if a particular user exists, make a GET request to the User API using their unique identifier. For more details on available parameters and response structure, refer to the Get User Endpoint.

Example Request​

curl -X GET "https://<api-host>/users/user_123" \
     --header "x-api-key: key_123456789"

Example Response​

{
  "id": "user_123",
  "email": "user@example.com",
  "type": "BUSINESS",
  "first_name": "John",
  "last_name": "Doe",
  "status": "ACTIVE"
}

If the API returns a user object, proceed with updating their details or generating a login link. If no user is found, move to Step 2: Create a User.

Step 2: Create or Update a User​

If the user does not exist in your system, create a new user account using their available details. Creating a user ensures they have access to your application through the passwordless process.

For existing users whose details have changed, update their information to maintain accurate records. This is particularly important when handling role-based access or email updates.

Creating a New User​

To create a new user, send a POST request to the User API with the required details, including their first name, last name, and email.

curl -X POST "https://<api-host>/users" \
     -H "x-api-key: <YOUR_API_KEY>" \
     -H "Content-Type: application/json" \
     -d '{
       "first_name": "John",
       "last_name": "Doe",
       "email": "user@example.com"
     }'

A successful request will return a response containing the newly created user's information, including their unique user ID.

Updating an Existing User​

To modify an existing user's details (e.g., name change, email update, or role adjustment), send a PUT request.

For more information, refer to the Update User Endpoint.

Step 3: Update User Status​

After verifying and creating a user, you may need to activate or deactivate their account based on business requirements.

Common reasons for updating a user's status include:

  • Activating a new user account to enable access
  • Deactivating an account due to security concerns or inactivity

Example Request: Activating a User​

curl -X PUT "https://<api-host>/users/user_123/status" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "status": "ACTIVE"
     }'

A successful request will return a confirmation message indicating the user's status change.

After verifying, creating, or updating a user, generate a passwordless login link. This link enables users to log in directly without entering a password.

  • Single-use authentication link
  • Grants the same permissions as a regular login session
  • Simplifies the login process by eliminating password entry

Warning: The passwordless login link is valid for one-time use only. Once used, it cannot be reused. Users must access it within the allowed timeframe.

API Endpoint​

POST /v1/users/{id}/login_url

Example Request​

curl -X POST "https://<api-host>/v1/users/user_123/login_url" \
     -H "x-api-key: YOUR_API_KEY"

Example Response​

{
  "login_url": "https://app.example.com/auth/magic-link?code=abc123"
}

Send this link to the user through email or another secure communication channel.

Summary​

Following these steps enables successful integration of passwordless login into your account portal.

Key Steps:​

  1. Verify User Details – Check if the user exists
  2. Create or Update a User – Add new users or update existing information
  3. Update User Status – Manage user access through activation or deactivation
  4. Generate a Passwordless Login Link – Provide secure, password-free authentication

If you encounter implementation issues:

  • Check API responses for error messages
  • Verify your API key has the correct permissions
  • Review request formats and required parameters

For additional support, refer to our API Documentation or contact our technical support team.