Skip to main content

Magic Links Passwordless Authentication

Magic links are a type of passwordless authentication that sends a unique login link containing a one-time code (the "magic link") to your user's email. Clicking the link allows your user to log in directly, with each link being accessible for a limited time and valid for single use only.

From a developer standpoint, the magic links process involves two main steps: requesting an email verification link and redeeming the email verification link.

Parameters​

  • dns: tenant domain as shown in the dashboard
  • communityName: tenant community as shown in the dashboard
  • licenseKey: tenant license key as shown in the dashboard
  • emailTo: email to send a magic link
  • emailSubjectOrNull: email subject line - enter null if you wish to omit
  • emailTemplateB64OrNull: email template, base64 encoded (see below for example) - enter null if you wish to omit
  • ttlSecondsOrNull: time to live before email verification link expires - enter null if you wish to omit
  • createdBy: Include a developer reference of who created the verification link
  • code: unique code sent to the requesting email address

Request Format​

tip

All requests are plug-and-play, not copy-paste. Please ensure that you are replacing the parameters in the request format below with the actual values for your tenant

  • Set tenant info
const BIDAccessCodes = require('blockid-nodejs-helpers/BIDAccessCodes');

const tenantInfo = {
    dns: "<dns>",
    communityName: "<communityName>",
    licenseKey: "<licenseKey>"
}
  • Set email recipient, email subject, and email template 
let emailTo = '<requesting email address>'; 

//NOTE: Email template must have {{MAGICLINK}} variable
const emailTemplate = `Click the button below to log in to 1Kosmos Developer Experience. https://${tenantInfo.dns}/devportal/demo?code={{MAGICLINK}}&tab=magiclinks&type=user_signin
This link will expire in 20 minutes.`;

const emailSubjectOrNull = 'Here is your Magic Link!';
let ttlSecondsOrNull = 1;
let createdBy = null;
tip

Your email template must include the {{MAGICLINK}} variable as shown above to receive a valid magic link

  • base64-encode the email template
const emailTemplateB64OrNull = emailTemplate ? Buffer.from(emailTemplate).toString('base64') : null;
  • Trigger and send the email containing the magic link: 
const requestEmailVerificationResponse = await BIDAccessCodes.requestEmailVerificationLink(tenantInfo, emailTo, emailTemplateB64OrNull, emailSubjectOrNull, createdBy, ttlSecondsOrNull);
  • Call function to verify and redeem magic links code 
const redeemVerificationCodeResponse = await BIDAccessCodes.verifyAndRedeemEmailVerificationCode(tenantInfo, requestEmailVerificationResponse.code);
  • Return verification code response 
return redeemVerificationCodeResponse

Example Request​

tip

Dummy information is provided in this example

const BIDAccessCodes = require('blockid-nodejs-helpers/BIDAccessCodes');

// Define tenant DNS, community name, and license key.
const tenantInfo = {
    dns: 'blockid-trial.1kosmos.net',
    communityName: 'default',
    licenseKey: "14cd5e85-a422-442a-9a8c-000000000000"
}

let emailTo = 'tom.smith@company.com'; // Requesting email address 

//NOTE: Email template must have {{MAGICLINK}} variable
const emailTemplate = `Click the button below to log in to 1Kosmos Developer Experience. https://${tenantInfo.dns}/devportal/demo?code={{MAGICLINK}}&tab=magiclinks&type=user_signin
This link will expire in 20 minutes.`;
const emailSubjectOrNull = 'Here is your Magic Link!';
let ttlSecondsOrNull = 1;
let createdBy = null;

async function testMagicLink(emailTo, emailTemplate, emailSubjectOrNull, ttlSecondsOrNull=1) {

    const emailTemplateB64OrNull = emailTemplate ? Buffer.from(emailTemplate).toString('base64') : null;

    const requestEmailVerificationResponse = await BIDAccessCodes.requestEmailVerificationLink(tenantInfo, emailTo, emailTemplateB64OrNull, emailSubjectOrNull, createdBy, ttlSecondsOrNull);
    
    const redeemVerificationCodeResponse = await BIDAccessCodes.verifyAndRedeemEmailVerificationCode(tenantInfo, requestEmailVerificationResponse.code);
    
    return redeemVerificationCodeResponse
}

testMagicLink(emailTo, emailTemplate, emailSubjectOrNull, ttlSecondsOrNull).then(response => {
    console.log('Magic Link output::', response);
})

Server Responses​

Request Email Verification​

200 OK
  {
      "emailResult": {
        "status": true,
        "statusCode": 200,
        "message": "https://blockid-trial.1kosmos.net/acr",
        "error": null,
        "gatewayId": "619cd2d01f74af757bb00000",
        "gatewayName": "Default Email Gateway",
        "resultId": "32d36f7f-ea59-4ad2-9235-d847cc700000",
        "messageId": "fecf1e76-5851-42f0-9b9a-172b4f400000",
        "ts": 1656480123
      },
      "link": "2927269a-deba-4f48-ba8c-9d6ee7900000",
      "code": "2927269a-deba-4f48-ba8c-9d6ee7900000",
      "statusCode": 200
    }

The verification request email was accepted, and a magic link code was generated.

Verify and Redeem Email Verification​

200 Success
{
    "message": "redeemed",
    "ttl_seconds": 14400,
    "type": "verification_link",
    "phoneRequired": false,
    "uuid": "2927269a-deba-4f48-ba8c-000000000000",
    "ttl": 0,
    "tenantId": "5f3d8d0cd866fa6100000000",
    "createdTime": 1656480123,
    "id": "62bbe17b5e3e7a5300000000",
    "communityId": "5f3d8d0cd866fa6100000000",
    "accesscodepayload": {
        "otp_email": "tom.smith@company.com",
        "authType": "none",
        "invite_email": "tom.smith@companyy.com"
    },
    "status": "redeemed",
    "statusCode": 200
}

Magic links code was successfully redeemed by the requesting email.