Request One-Time Passcode
Use the BlockID SDK to request a one-time passcode to your user's phone number or email address.
Request One-Time Passcode
After configuring the SDK with your tenant information and license key found on the BlockID Developer Dashboard, you are ready to request a one-time passcode.
Parameters
dns
: Your tenant domain as shown in the dashboardcommunityName
: Your tenant communnity name as shown in the dashboardlicenseKey
: Your tenant license key as shown in the dashboardusername
: Your registered full email addressemailToOrNull
: Email to send OTP - enternull
to omitsmsToOrNull
: Phone number, including area code, to send OTP - enternull
to omitISDCodeOrNull
: International subscriber dialing code of the phone number - enternull
to omit
Not all the parameters are necessary for each request. To send an OTP to only an email, or only a phone number, omit the parameters you don't wish to use.
If you omit both the phone and email, the OTP will be returned in the body of the server response
Request Format
- NodeJS SDK
- PHP SDK
- Java SDK
- .NET SDK
- Set tenant info and request OTP
const BIDOTP = require('blockid-nodejs-helpers/BIDOTP');
let otpResponse = await BIDOTP.requestOTP({ "dns": "<dns>", "communityName": "<communityName>", "licenseKey": "<licenseKey>" }, "<username>", "<emailToOrNull>", "<smsToOrNull>", "<smsISDCodeOrNull>");
- Set tenant info and request OTP
<?php
require_once("./BIDTenant.php");
require_once("./BIDOTP.php");
$tenantInfo = array("dns" => "<dns>", "communityName" => "<communityName>", "licenseKey" => "<licenseKey>");
$otpResponse = BIDOTP::requestOTP($tenantInfo, "<userId>", "<emailorNull>", "<phoneOrNull>", "<countryCode>");
?>
- Set tenant info and request OTP
BIDTenantInfo tenantInfo = new BIDTenantInfo("<dns>", "<communityName>", "<licenseKey>");
BIDOtpResponse otpResponse = BIDOTP.requestOTP(tenantInfo, "<username>", "<emailToOrNull>", "<smsToOrNull>", "<ISDCodeOrNull>");
- Set tenant info and request OTP
using BIDHelpers.BIDOTP;
using BIDHelpers.BIDOTP.Model;
using BIDHelpers.BIDTenant.Model;
BIDTenantInfo bidTenantInfo = new BIDTenantInfo("<dns>", "<communityName>", "<licenseKey>");
BIDOtpResponse requestOtp = BIDOTP.RequestOTP(bidTenantInfo, "<userName>", "<emailToOrNull>", "<smsToOrNull>", "<smsISDCodeOrNull>");
Example OTP Request
We've provided some example OTP requests using the BlockID SDK.
These are just examples - you will probably want to configure your development environment to request a one-time passcode as part of a sign-in request or something similar.
- NodeJS SDK
- PHP SDK
- Java SDK
- .NET SDK
Example OTP Request - SMS and Email
Send a one-time passcode to both a user's phone number and an email. The same passcode will be sent simultaneously to the number and email entered.
const BIDOTP = require('blockid-nodejs-helpers/BIDOTP');
let otpResponse = await BIDOTP.requestOTP({ "dns": "blockid-trial.1kosmos.net", "communityName": "devx", "licenseKey": "0005c9f8-1918-40be-aa00-e319043f7xxx" }, "john.smith", "john.smith@company.com", "5558675309", "1");
Example OTP Request - SMS Only
To send a one-time passcode to only a phone number, omit the email parameter.
const BIDOTP = require('blockid-nodejs-helpers/BIDOTP');
let otpResponse = await BIDOTP.requestOTP({ "dns": "blockid-trial.1kosmos.net", "communityName": "devx", "licenseKey": "0005c9f8-1918-40be-aa00-e319043f7xxx" }, "john.smith", null, "5558675309", "1");
Example OTP Request - Email Only
const BIDOTP = require('blockid-nodejs-helpers/BIDOTP');
let otpResponse = await BIDOTP.requestOTP({ "dns": "blockid-trial.1kosmos.net", "communityName": "devx", "licenseKey": "0005c9f8-1918-40be-aa00-e319043f7xxx" }, "john.smith", "john.smith@company.com", null, null);
Example OTP Request - Neither SMS nor Email (OTP Returned in Response Body)
const BIDOTP = require('blockid-nodejs-helpers/BIDOTP');
let otpResponse = await BIDOTP.requestOTP({ "dns": "blockid-dev.1kosmos.net", "communityName": "devx", "licenseKey": "9b074532-845b-4c75-ba3e-2b89598adxxx" }, "john.smith", null, null, null);
Example OTP Request - SMS and Email
Send a one-time passcode to both a user's phone number and an email. The same passcode will be sent simultaneously to the number and email entered.
<?php
require_once("./BIDTenant.php");
require_once("./BIDOTP.php");
$tenantInfo = array("dns" => "blockid-trial.1kosmos.net", "communityName" => "devx", "licenseKey" => "0005c9f8-1918-40be-aa00-e319043f7xxx");
$otpResponse = BIDOTP::requestOTP($tenantInfo, "john.smith@company.com", "john.smith@company.com", "8588675309", "1");
?>
Example OTP Request - SMS Only
To send a one-time passcode to only an email address or phone number, simply omit the parameters that you do not wish to use.
<?php
require_once("./BIDTenant.php");
require_once("./BIDOTP.php");
$tenantInfo = array("dns" => "blockid-trial.1kosmos.net", "communityName" => "devx", "licenseKey" => "0005c9f8-1918-40be-aa00-e319043f7xxx");
$otpResponse = BIDOTP::requestOTP($tenantInfo, "john.smith@company.com", null, "8588675309", "1");
?>
Example OTP Request - Email Only
<?php
require_once("./BIDTenant.php");
require_once("./BIDOTP.php");
$tenantInfo = array("dns" => "blockid-trial.1kosmos.net", "communityName" => "devx", "licenseKey" => "0005c9f8-1918-40be-aa00-e319043f7xxx");
$otpResponse = BIDOTP::requestOTP($tenantInfo, "john.smith@company.com", "john.smith@company.com", null, null);
?>
Example OTP Request - SMS and Email
Send a one-time passcode to both a user's phone number and an email. The same passcode will be sent simultaneously to the number and email entered.
BIDTenantInfo tenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "0005c9f8-1918-40be-aa00-e319043f7xxx");
BIDOtpResponse otpResponse = BIDOTP.requestOTP(tenantInfo, "john.smith@company.com", "john.smith@company.com", "5558675309", "1");
Example OTP Request - SMS Only
To send a one-time passcode to only an email address or phone number, simply omit the parameters that you do not wish to use.
BIDTenantInfo tenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "0005c9f8-1918-40be-aa00-e319043f7xxx");
BIDOtpResponse otpResponse = BIDOTP.requestOTP(tenantInfo, "john.smith@company.com", null, "5558675309", "1");
Example OTP Request - Email Only
To send a one-time passcode to only an email address or phone number, simply omit the parameters that you do not wish to use.
BIDTenantInfo tenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "0005c9f8-1918-40be-aa00-e319043f7xxx");
BIDOtpResponse otpResponse = BIDOTP.requestOTP(tenantInfo, "john.smith@company.com", "john.smith@company.com", null, null);
Example OTP Request - SMS and Email
Send a one-time passcode to both a user's phone number and an email. The same passcode will be sent simultaneously to the number and email entered.
using BIDHelpers.BIDOTP;
using BIDHelpers.BIDOTP.Model;
using BIDHelpers.BIDTenant.Model;
BIDTenantInfo bidTenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "0005c9f8-1918-40be-aa00-e319043f7xxx");
BIDOtpResponse requestOtp = BIDOTP.RequestOTP(bidTenantInfo,, "john.smith@company.com", "john.smith@company.com", "5558675309", "1");
Example OTP Request - SMS Only
To send a one-time passcode to only an email address or phone number, simply omit the parameters that you do not wish to use.
using BIDHelpers.BIDOTP;
using BIDHelpers.BIDOTP.Model;
using BIDHelpers.BIDTenant.Model;
BIDTenantInfo bidTenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "0005c9f8-1918-40be-aa00-e319043f7xxx");
BIDOtpResponse requestOtp = BIDOTP.RequestOTP(bidTenantInfo, "john.smith@company.com", null, "5558675309", "1");
Example OTP Request - Email Only
To send a one-time passcode to only an email address or phone number, simply omit the parameters that you do not wish to use.
using BIDHelpers.BIDOTP;
using BIDHelpers.BIDOTP.Model;
using BIDHelpers.BIDTenant.Model
BIDTenantInfo bidTenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "0005c9f8-1918-40be-aa00-e319043f7xxx");
BIDOtpResponse requestOtp = BIDOTP.RequestOtp(bidTenantInfo, "john.smith@company.com", "john.smith@company.com", null, null);
Example Server Response
The SDK will return an immediate response from our API. The responses are the same across each SDK and are JSON formatted. Possible response codes you might receive include:
Server Responses
- 200 (OTP Sent to Email or SMS)
- 200 (OTP in Response Body)
- 401
- 403
- 404
{
"messageId":"15f9dd86-9a8a-4c66-900a-f711f5acceb1",
"info":"OTP request accepted"
}
The API accepted the OTP request and sent a one-time passcode to the phone or email.
If you did not enter an email or an SMS and left these values as null, the OTP will be returned in the response body:
{
"data": "MzY1M2IwZjYyOTViNTBkOEu11D19Ep7W4XrQKiFlR9430OnLqxMYW3UkW2VBNHu2Qw==",
"messageId":"15f9dd86-9a8a-4c66-900a-f711f5acceb1",
"info":"OTP request accepted",
"response": { "code": "518321" }
}
{
"error_code": 401,
"message":"Unauthorized"
}
The request was not authorized.
{
"error_code": 403,
"message":"OTP locked for the user"
}
The incorrect one-time passcode was entered more than five times in 24 hours, resulting in an account lockout. User accounts will automatically unlock after 30 minutes.
{
"error_code": 404,
"message":"Unable to load tenant/community"
}
When the user requests the one-time passcode (OTP), user can find the tenant and license key information that has been set on the user dashboard.