OTPfy SDK

This Node package will provide you with the interface to interact with your OTPfy services like generate and validate.

SDK installation

yarn add @otpfy/sdk

npm i --save @otpfy/sdk

SDK import

import sdk from '@otpfy/sdk';

const sdk = require('@otpfy/sdk');

SDK initialization

In order for a successful initialization your team private key needs to be passed as the only argument to the initialization function. Make sure that this private key is always safe and secure so nobody can make requests on your team's behalf.

import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');

node-fetch as a peer dependency

This module requires the use of node-fetch as a dependency but it's not bundled with the SDK to avoid increasing the bundle size. This means that you will have to separately install node-fetch as a dependency of your backend project.

SDK interface

export interface OTPfySDK {
  generateOTP: (
    config: GenerateConfig
  ) => Promise<GenerateSuccessResponse | GenerateErrorResponse>;
  verifyOTP: (
    config: VerifyConfig
  ) => Promise<VerifySuccessResponse | VerifyErrorResponse>;
  generateMagicLink: (
    config: GenerateMagicLinkConfig
  ) => Promise<GenerateSuccessResponse | GenerateErrorResponse>;
  checkLicense: () => Promise<LicenseStatus>;
}

type GenerateConfig = {
  key: string;
  external_identifier: string;
  email: string;
  phone?: string;
};

type GenerateMagicLinkConfig = {
  key: string;
  external_identifier: string;
  email: string;
  callbacks: {
    success: string;
    error: string;
  };
};

type VerifyConfig = {
  key: string;
  identifier: string;
  external_identifier: string;
  code: string;
};

export type GenerateSuccessResponse = {
  status: 200;
  code: string;
  identifier: string;
};

export type GenerateErrorResponse = {
  status: number;
  code: string;
  message?: string;
};

export type VerifySuccessResponse = {
  status: 200;
  code: string;
};

export type VerifyErrorResponse = {
  status: number;
  code: string;
  message?: string;
};

export type LicenseStatus = {
  code: 'BAD_REQUEST' | 'UNAUTHORIZED' | 'VALID_LICENSE' | 'TEAM_BLOCKED';
};

OTP generation

For OTP generation the generateOTP method from the SDK must be called with a configuration object:

import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');

const generateResponse = await otpfy.generateOTP({
  email: '[email protected]',
  external_identifier: '978c324ab78dd92',
  key: 'AUTH',
});

sdk.generateOTP(config) will return you the a GenerateSuccessResponse with the unique OTP identifier that later on will be used to verify the generated code and the user input or GenerateErrorResponse if the generation was not successful.

Let's dive into the GenerateConfig properties:

key

key: string;

This property will take the OTP key string generated on your OTPfy dashboard.

external_identifier

external_identifier: string;

Unique identifier provided on your side to identify this OTP. Commonly this could be your user's ID or some unique identifier.

email

email: string;

An email will be sent to this target email with the generated OTP based on the template created and chosen on your OTPfy dashboard.

phone (not supported yet)

phone?: string;

A SMS will be sent to this target phone with the generated OTP based on the template created and chose on your OTPfy dashboard.

OTP verification

For OTP verification the verifyOTP method from the SDK must be called with a configuration object:

import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');

const verifyResponse = await otpfy.verifyOTP({
  code: '45$6AFd65',
  external_identifier: '978c324ab78dd92',
  key: 'AUTH',
  identifier: '123cb8945bd0943',
});

sdk.verify(config) will return you a VerifySuccessResponse or VerifyErrorResponse that will let you know if the verification was successful or not.

Let's dive into the VerifyConfig properties:

code

code: string;

The code that the user has received and you'd like to check.

external_identifier

external_identifier: string;

Unique identifier provided on your side to identify the OTP previously generated. Commonly this could be your user's ID or some unique identifier.

key

key: string;

This property will take the OTP key string generated on your OTPfy dashboard.

identifier

identifier: string;

The unique OTP identifier that was returned by the sdk.generate(config) call that will make sure that the correct OTP is verified.

Magic Link generation

For OTP generation the generateOTP method from the SDK must be called with a configuration object:

import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');

const generateResponse = await otpfy.generateMagicLink({
  email: '[email protected]',
  external_identifier: '978c324ab78dd92',
  key: 'AUTH',
  callbacks: {
    success: 'https://myapp.com/authentication/success?id=123123123
    error: 'https://myapp.com/authentication/error?id=123123123
  }
});

sdk.generateMagicLink(config) will return you a GenerateSuccessResponse or GenerateErrorResponse if the generation was not successful.

Let's dive into the GenerateMagicLinkConfig properties:

key

key: string;

This property will take the Magic Link key string generated on your OTPfy dashboard.

external_identifier

external_identifier: string;

Unique identifier provided on your side to identify this Magic Link. Commonly this could be your user's ID or some unique identifier.

email

email: string;

An email will be sent to this target email with the generated Magic Link based on the template created and chosen on your OTPfy dashboard.

callbacks

callbacks: {
  success: string;
  error: string;
}

A callback object that will be used by OTPfy to redirect the user to the given URLs after the Magic Link verification has succeeded or not, redirecting to callbacks.success if the verification was successful or to callbacks.error if the verification was unsuccessful.

Check License

You can use this handy method from the OTPfy SDK in order to check your team's current license status.

const licenseStatus = await otpfy.checkLicense();

licenseStatus will hold a string literal with any of the following values and meanings:

• VALID_LICENSE

  Your current license is valid and you can make use and have access to any of the OTPfy services.

• UNAUTHORIZED

  The provided team private key at the initialization of the SDK was not valid and therefore, you're not authorized to check for license statuses.

• TEAM_BLOCKED

  Your team is currently blocked from using the OTPfy services due to an unpaid overdue invoice. Please, access your dashboard at https://otpfy.com/license and proceed with the payment of the invoice in order to unblock the license and continue using the OTPfy services.

GenerateSuccessResponse example

{
  status: 200,
  code: 'SUCCESS',
  identifier: 'example-identifier'
}

GenerateErrorResponse example

{
  status: 400,
  code: 'BAD_REQUEST'
}

VerifySuccessResponse example

{
  status: 200,
  code: 'SUCCESS`
}

VerifyErrorResponse example

{
  status: 400,
  code: 'BAD_REQUEST'
}