Magic Links for Passwordless Login

Overview

The Magic Links endpoint allows company admins and employees to log in to the Remote platform without using a password. The generated magic link redirects the user to a specific section of the Remote platform based on the provided parameters.

ℹ️ This feature is disabled by default. To enable it, please reach out to your integration contact in Remote or [email protected].

Create Magic Link

The Generate magic link endpoint allows you to create a new magic link for passwordless authentication. Any company manager with a company-scoped access token can create a magic link for company admins and employees by providing their ID.

ℹ️ Magic links can only be created for employees that have invited status, meaning they have access to the Remote platform.

For a successful call, provide a user_id with path parameter or an employment_id with path. These parameters are:

• user_id: To generate a magic link request for a company manager, their user ID needs to be provided. This ID can be retrieved by calling the List company managers endpoint.
• employment_id: To generate a magic link request for an employee, provide their employment ID. This ID corresponds to the id returned when the employment was created. You can call the List employments endpoint to retrieve it from the response.
• path: This represents the URL path to which the user will be redirected after logging in. A few important points to note about this parameter:
  • This is an optional parameter. If a value is not specified, /dashboard will be used by default.
  • Maximum length of this string is 255 characters.
  • The string must begin with a / and contain at least one path segment. For example /dashboard.
  • The string value cannot end with a /.
  • Path segments can only include alphanumeric characters, underscore _, and hyphen -.
  • An optional query string can be included starting with a ?.
  • Query keys and values may include alphanumeric characters, underscore _, hyphen -, or percent-encoded values (e.g., %20 for space).
  • Multiple query key-value pairs can be separated using &.
  • Query keys require at least one valid character. Values are optional, and the = sign may be omitted.
  
  Taking these points into consideration, some valid values for the `path` parameter are:
  • /dashboard
  • /dashboard/people/new/full_time/663e0b79-c893-45ff-a1b2-f6dcabc098b5
  • /dashboard/people/hiring?filters%5B0%5D%5Bid%5D=exclude_linked_drafts&filters%5B0%5D%5Bvalue%5D=true
  • /dashboard?key=value&foo=bar

A valid API call looks like this:

{
  "user_id": "fcfe5f21-8a08-4c9a-9f97-29d2fd6a27b9",
  "path": "/dashboard/people/hiring?filters%5B0%5D%5Bid%5D=exclude_linked_drafts&filters%5B0%5D%5Bvalue%5D=true"
}

ℹ️ Please note that one API call will generate a magic link for one user/employee at a time.

This will return a magic link url that is the redirection link for that specific user.

{
  "data": {
    "url": "https://remote.com/magic-link/OWIEkmS4jIa3PdPgjrU5QBLfmxKom15y2f1bK2HgFeekcrIKdMxCKYyKWIG3Yc3cUAzHJDebd0ZXqLQI1HFD0mpSPzjcSOv6dlP3Ox6IpfJu1JCO2VjXRkrMUT3m"
  }			
}

ℹ️ This magic link url expires in 3 minutes and can only be used one time.

Magic links behavior

• If only the ID is provided, the user will be redirected to /dashboard.
• If path is provided along with the ID, then the user will be redirected to the specified path.
• If the provided ID does not have permission to access the path, the user will be redirected to the default /dashboard path.
• If the user has 2 factor authentication (2FA) enabled, it will be enforced when logging in with magic link.
• Magic links remain valid even if the user sets a password on Remote platform.
• Magic links are not supported on mobile devices.

Use case

Let's say you hired a new company manager whose main role at your company is to manage the offboarding of employees. You can set a magic link for that user so every time they log in, they are automatically redirected to the offboarding page. Here's how that request will look like:

{
  "user_id": "fcfe5f21-8a08-4c9a-9f97-29d2fd6a2799",
  "path": "/dashboard/offboarding?selectedTab=employee"
}

Similarly, if you hired a new employee and want to ensure that they are redirected to their profile page in Remote, you can send the following in the generate magic link's request body:

{
  "employment_id": "20a72f86-employment-id-9e4942a902ff",
  "path": "/dashboard/personal-details/?selectedTab=personal"
}

If you face any issues, please reach out to our support team for assistance.