devoted-promote v0.0.24

Devoted Technologies Promote

Promote is a hosted solution that allows you to send verification codes, either by email or by SMS, to your customers.

Promote can be used in various ways, for example allowing your customers to authenticate to your system without the need to store a password at your side. Simply issue a verification code and we'll take care of the rest.

Another way might be to easily add support for two factor authentication to your existing application.

Interested? Since you'll require an API key, please contact us directly to get access.

Quick start

npm i --save devoted-promote

How it works

When your customer wants to sign in using Promote, you need to initialize a transaction which will be used to uniquely identify the authentication process. To initialize a transaction, you need to pass along a successUrl and an errorUrl to which your customer will be accordingly redirected to based on the result of the authentication.

The successUrl must contain a placeholder for the transaction ID mentioned above, so that you are able to retrieve the status of the transaction when your customer is redirected back to your application.

The errorUrl is used to redirect your customer to if multiple verification attempts fail, in which case the transaction will be considered aborted.

After you've initialized a transaction, the transaction ID (id) as well as the redirect URL (url) to Promote will be returned. Use the generated URL to redirect your customer to authenticate.

Once your customer has successfully verified their identity, they will be redirected to your application given the provided success URL. At this point, you'll be able to retrieve the passed transaction ID and verify the status of the transaction. If the transaction was completed successfully, you can safely grant your customer access to your application like you would normally do when authenticating with username and password. (For example by issuing a JWT, Cookie, or whatever you prefer.)

Usage

JavaScript

// Require Promote
const Promote = require('devoted-promote').Promote

// Create a new instance of Promote
const promote = new Promote('<apiKey>')

// Initialize a transaction
promote.initialize({
  successUrl: 'https://your-application.com/signin/success?transactionId={transactionId}',
  errorUrl: 'https://your-application.com/signin/error'
}).then((response) => {
  // Unique transaction ID
  const transactionId = response.id

  // Redirect URL
  const redirectUrl = response.url
}, (error) => {
  // Something went wrong
  console.error(error)
})

// Retrieve transaction information
promote.get({
  id: '<transactionId>'
}).then((response) => {
  // Unique transaction ID
  const transactionId = response.id

  // Customer subject (email address or phone number)
  const subject = response.subject

  // Unix timestamp of the transaction creation time
  const timestamp = response.timestamp

  // Delivery type of the verification code ('sms' | 'email')
  const type = response.type

  // Most importantly, status of the transaction ('initialized' | 'issued' | 'completed' | 'aborted')
  const status = response.status
}, (error) => {
  // Something went wrong
  console.error(error)
})

TypeScript

// Import Promote
import { Promote } from 'devoted-promote'

// Create a new instance of Promote
const promote = new Promote('<apiKey>')

// Have a look at the JavaScript implementation for more detailed information

// Initialize a transaction
try {
  const response = await promote.initialize(...)
} catch (error) {
  console.error(response)
}

// Retrieve transaction information
try {
  const response = await promote.get(...)
} catch (error) {
  console.error(response)
}