@otpfy/sdk v2.3.1
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: 'no-reply@otpfy.com',
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: 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: 'no-reply@otpfy.com',
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: 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'
}