Introduction
<?php
// Code examples will appear here.
echo "Hello, Tozny";
?>
// Code examples will appear here.
System.out.println("Hello, Tozny!");
# Code examples will appear here.
puts "Hello, Tozny"
# Code examples will appear here.
echo "Hello, Tozny"
// Code examples will appear here.
NSLog(@"Hello, Tozny!");
// Code examples will appear here.
print("Hello, Tozny!")
// Code examples will appear here.
Log.d(TAG, "Hello, Tozny!");
Tozny’s password-free authentication platform enables your users to sign up for and authenticate to your web site in a way that’s faster, easier, and more secure than passwords. In this guide, you will learn how to:
- Create a Tozny realm for your web site
- Enroll users in your realm using the API or Tozny web interface
- Authenticate users to your web site
Throughout this guide, code samples will appear on the right-hand side in one of the programming languages supported by our SDK. Simply select the desired language tab to display code samples and reference material in that language.
Realm Creation
Creating a Tozny account is easy and free! Sign up for our pilot program by filling out our Beta Contact Form and we will create your realm and help guide you through the integration process.
User Enrollment
Before a user can log in to your web site or mobile application using Tozny, they must be enrolled with your realm. To enroll a user, you must complete the following steps:
- The user has been created in your Tozny realm
- The user has created a private key on at least one device that they will use to log in with
Often, when integrating Tozny with an existing user database that uses passwords, there will be several additional steps when enrolling a user:
- Create an account in your web site’s user database
- Associate the Tozny user ID with your internal user ID
These topics will be discussed in more detail in the “Authentication” section of this guide.
Using Verified E-Mail Addresses
Tozny offers email verification functionality that flows seamlessly into user enrollment and authentication. By generating a short-lived email challenge, often called a Magic Link, Tozny can take a user from on-boarding through to cryptographically secure, password-free login with minimal effort for the user.
The following steps outline the Email Verification, Enrollment, and Login processes.
Email Verification
// There is no code example for this language.
# There is no code example for this language.
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.LinkChallenge;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
import com.tozny.sdk.realm.methods.user_add.UserAddResponse;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi realmApi = new RealmApi(config);
// generate link challenge to email to the user
String context = "enroll";
Integer secondsValid = 86400; // 24 hours
String verificationEndpoint = "https://yoursite.com/verify";
boolean haveToznySendEmail = false;
LinkChallenge challenge = realmApi.linkChallenge("user@example.com", verificationEndpoint, secondsValid, context, haveToznySendEmail, null);
String magicLink = challenge.getUrl().toString();
System.out.println("Send this link via e-mail: " + magicLink);
# There is no code example for this language.
// Tozny mobile SDKs do not support magic link generation
// Tozny mobile SDKs do not support magic link generation
// Tozny mobile SDKs do not support magic link generation
The magic link would look something like this:
Send this link via e-mail: https://yoursite.com/verify?toznyo=c5a414fbeed42c59f374c1c1a40634f2&toznyr=YOUR-REALM-KEY-ID
- User enters their email into your application, which is then sent to your back-end for validation
- Use a Tozny back-end SDK (e.g. php, ruby, java, etc.) to generate a
LinkChallenge
for enrollment, formatting the challenge to point to your website. Enable your mobile app to capture this link to forward to your back-end. NOTE The magic link supplies its random challenge as atoznyo
url parameter.
Enrollment
// There is no code example for this language.
# There is no code example for this language.
import com.tozny.sdk.UserApi;
import com.tozny.sdk.user.Result;
import com.tozny.sdk.user.EnrollmentChallenge;
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi realmApi = new RealmApi(config);
UserApi userApi = new UserApi("YOUR-REALM-KEY-ID");
// one-time-password (OTP) parsed from your endpoint url,
// with the parameter `toznyo`
Result result = userApi.linkResult("OTP-FROM-YOUR-ENDPOINT");
// check for errors
if (result.isError()) {
// an error occurred
System.out.println("Error: " + result.getException().getMessage());
} else {
try {
// verify payload received from mobile app
String signedData = result.getSigned_data();
String signature = result.getSignature();
if (this.realmApi.verifyLogin(signedData, signature)) {
// exchange the link result for a Tozny enrollment challenge
EnrollmentChallenge challenge = userApi.enrollmentChallengeExchange(signedData, signature);
if (!challenge.isError()) {
// send back to mobile app
System.out.println("Enrollment challenge: " + challenge.getSecretEnrollmentUrl());
}
}
}
catch (ToznyApiException e) { System.out.println("Error: " + e.getMessage()); }
}
# There is no code example for this language.
#import <Tozny.h>
// ...
Tozny *tozny = [[Tozny alloc] init];
ToznyChallenge *enrollmentChallenge = [[ToznyChallenge alloc] initWithChallengeURL:[NSURL URLWithString:@"ENROLLMENT-CHALLENGE-URL"]];
[tozny enrollUserWithChallenge:enrollmentChallenge
realmKeyID:@"YOUR-REALM-KEY-ID"
userOptions:nil
completion:^(ToznyUser * _Nullable newUser, NSError * _Nullable error) {
if (error) { return NSLog(@"Error enrolling user %@", error.localizedDescription); }
// User is enrolled
NSLog(@"User: %@ or Error: %@", newUser, error);
}];
import ToznyCore
//...
let tozny = Tozny();
guard let url = NSURL(string: "ENROLLMENT-CHALLENGE-URL") else { return print("failed to create url") }
let enrollmentChallenge = ToznyChallenge.init(challengeURL: chUrl)
tozny.enrollUserWithChallenge(enrollmentChallenge, realmKeyID: "YOUR-REALM-KEY-ID", userOptions: nil) { (newUser, error) in
guard let user = newUser else { return print("Error enrolling user \(error?.localizedDescription)") }
// User is enrolled
print("User: \(user) ID: \(user.userID)")
}
import com.tozny.sdk.*;
// ...
Tozny tozny = new Tozny("APP-CONTEXT-HERE");
ToznyChallenge enrollmentChallenge = new ToznyChallenge("ENROLLMENT-CHALLENGE-URL");
tozny.enrollUser("YOUR-REALM-KEY-ID", enrollmentChallenge, options, new EnrollmentHandler() {
@Override
public void didCreateAccount(ToznyUser user, ToznyRealm realm) {
// User is enrolled
Log.d(TAG, "UserID: " + user.userID);
}
@Override
public void failToCreateAccount(ToznyException e) {
Log.d(TAG, "Error enrolling user");
}
});
The enrollment challenge would look something like this:
Enrollment challenge: tozadd://api.tozny.com/?k=0c95a95d129423530a024bc21e9073208ee1790b5115172f46b0920a1e08d7a1&r=YOUR-REALM-KEY-ID
- Use the Tozny SDK to provide a link
Result
of either an email verification or an error (e.g. link expired, etc.) - If the email verification was successful, you can use the SDK to perform an
enrollmentChallengeExchange
with the verification result to get a ToznyEnrollmentChallenge
- Forward this challenge to your mobile app and use a Tozny mobile-sdk
to
enrollUser
which will generate a cryptographic key pair on the device
Login
// There is no code example for this language.
# There is no code example for this language.
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi realmApi = new RealmApi(config);
try {
// verify payload received from mobile app
if (realmApi.verifyLogin("USER-SIGNED-DATA", "USER-SIGNATURE")) {
// user logged in!
System.out.println("Generate JWT and send to mobile app!");
}
}
catch (ToznyApiException e) { System.out.println("Error: " + e.getMessage()); }
# There is no code example for this language.
#import <Tozny.h>
// ...
Tozny *tozny = [[Tozny alloc] init];
[tozny authenticateUserWithID:enrolledUser.userID
realmKeyID:@"YOUR-REALM-KEY-ID"
challenge:nil
userOptions:nil
completion:^(ToznyAuthentication * _Nullable authentication, NSError * _Nullable error) {
if (error) { return NSLog(@"Error authenticating user %@", error.localizedDescription); }
// user has authenticated with Tozny,
// return signed payload to back-end to exchange for JWT
NSLog(@"Authentication - signedPayload: %@ signature: %@", authentication.signedPayload, authentication.signature);
}];
import ToznyCore
//...
let tozny = Tozny();
tozny.authenticateUserWithID(enrolledUser.userID, realmKeyID: "YOUR-REALM-KEY-ID", challenge: nil, userOptions: nil) { (authentication, error) in
guard let auth = authentication else { return print("Error authenticating user \(error?.localizedDescription)") }
// user has authenticated with Tozny,
// return signed payload to back-end to exchange for JWT
print("Authentication - signedPayload: \(auth.signedPayload) signature: \(auth.signature)")
}
import com.tozny.sdk.*;
// ...
Tozny tozny = new Tozny("APP-CONTEXT-HERE");
tozny.authenticateUser("YOUR-REALM-KEY-ID", enrolledUser.getUserID(), null, null, new AuthorizationHandler() {
@Override
public void handleAuthorized(ToznyAuthentication auth) {
// user has authenticated with Tozny,
// return signed payload to back-end to exchange for JWT
Log.d(TAG, "Authentication - signedPayload: " + auth.getSignedPayload() +
" signature: " + auth.getSignature());
}
@Override
public void handleNotAuthorized(ToznyException e) {
Log.d(TAG, "Error authenticating user");
}
});
An authentication payload will look similar to this:
Authentication -
signedPayload:
eyJtZXRob2QiOiJyZWFsbS5jaGVja192YWxpZF9sb2dpbiIsIm1ldGEiOnsidG96bnlfdXNlcm5hbWUiOiJ0ZXN0X3VzZXIiLCJ0b3pueV9lbWFpbCI6InRlc3RAdXNlci5jb20ifSwidXNlcl9pZCI6InNpZF81N2M0N2VkNzA3YjBjIiwibm9uY2UiOiI1ODgzNWQxNTA4ODVkMjUzYTNmNjAxOTQ5NzQzYjAxNGNmMDdlZGYxNGMxNGMzMTBiMWQ1YjUzZDkxNmZkYWJhIiwicmVhbG1fa2V5X2lkIjoic2lkXzI3Njk2OTA5IiwiZXhwaXJlc19hdCI6MTQ3MjQ5ODE2NSwic2Vzc2lvbl9pZCI6ImNhNzdlNzNiMWNlMmJkOTY5Y2EwZGU1ZjEzMzJkZTcxYmFhOTI0ODhmNmQ0YzcyYTRmYmRhZWNiZjBjYmExZDUiLCJzaWduYXR1cmVfdHlwZSI6IkhNQUMifQ
signature: RGMtx9ZA8DcXMPJucGQvbxoXlxS1n-CCi1-ttB13_80
- Use the Tozny mobile-sdk to
authenticateUser
which will supply a signed payload and signature. - Forward this payload to your back-end and verify the signature – either with the Tozny SDK or yourself. If the signature matches… success! Your user has successfully logged in. At this point, you can generate a session token (JWT, etc.) to provide access.
Custom Enrollment Using the API
<?php
include("ToznyRemoteRealmAPI.php");
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$result = $api->userAdd('true', array(), null);
if (!$result) {
// An error occured while creating the user.
print("Error while creating user!\n");
} else {
// Option 1: Obtain a link to e-mail or text the user to click
// on their mobile device to complete enrollment:
$magic_link = $result["secret_enrollment_url"];
print("Send this link via e-mail or text: $magic_link\n");
// Option 2: Redirect the user to a page displaying a QR code they
// can scan from their device to complete enrollment:
$qr_url = $result["secret_enrollment_qr_url"];
print("Or ask the user to scan the QR code at: $qr_url\n");
}
require 'tozny/auth'
api = Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET')
result = api.user_add('true', nil, nil)
if !result
puts "Error while creating user!"
else
# Option 1: Obtain a link to e-mail the user to click on their mobile
# device to complete enrollment:
magic_link = result[:secret_enrollment_url]
puts "Send this link via e-mail: #{magic_link}"
# Option 2: Redirect the user to a page displaying a QR code they
# can scan from their device to complete enrollment:
qr_url = result[:secret_enrollment_qr_url]
puts "Or ask the user to scan the QR code at: #{qr_url}"
end
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
import com.tozny.sdk.realm.methods.user_add.UserAddResponse;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi api = new RealmApi(config);
UserAddResponse result = api.userAdd(true, null);
// Option 1: Obtain a link to e-mail the user to click on their mobile
// device to complete enrollment:
String magicLink = result.getSecretEnrollmentUrl();
System.out.println("Send this link via e-mail: " + magicLink);
// Option 2: Redirect the user to a page displaying a QR code they
// can scan from their device to complete enrollment:
String qrUrl = result.getSecretEnrollmentQrUrl();
System.out.println("Or ask the user to scan the QR code at: " + qrUrl);
# There is no code example for this language.
The Tozny SDK makes it easy to integrate our user enrollment process with your existing infrastructure for creating users.
For a normal realm that is not open (typically called a closed realm), you will create a user account using Tozny’s back-end SDK in a language such as PHP, Ruby, or Java. To complete the creation of the user account, you must deliver a temporary key to the user. Typically this is done by displaying a QR code or sending the challenge to the user’s mobile device directly (via SMS or e-mail, for example).
In the code example on the right, we create a user using the userAdd
SDK function, then show how to obtain a link which can be sent directly
or a link to a QR image to display.
Once the user has received the challenge, their mobile application will use the Tozny Mobile SDK to create a private key and complete the enrollment process.
Allowing Users to Self-Register
The simplest way to enroll users is to configure your realm to allow users to register their own accounts. A realm that is configured this way is said to be using open enrollment, or called an open realm.
An open realm is appropriate for some types of web site where users are allowed to create an account without verifying any personal information. However, for web sites that have a requirement to verify user information before creating an account, using another enrollment method is preferred.
You can set your realm to use open enrollment in the Tozny Web Console by following this process:
Log in to the Tozny Web Console.
Activate the pop-up menu in the upper right and select “Settings”.
Click the “Edit” button in the upper right to edit your realm settings.
Scroll down near the button and click “Open Enrollment” so that the toggle button show “YES”.
Click “Save” to save your realm settings.
From now on, when a user visits your web site and scans the Tozny QR code, they will be prompted to create an account if they do not already have one. The user will supply their e-mail address, but this is not validated by the system.
To see an open realm in action, visit the Tozny Bank Demo site and note that you are able to create an account from your mobile device without performing any additional validation.
User Authentication
Tozny’s login API is extremely easy to integrate with. In this section, we walk you through an example integration of Tozny with simple web front and back end infrastructure.
Prerequisites
Before starting, this tutorial assumed you have the following task completed already:
- Have a working Tozny API Key. You can learn how to retrieve your Tozny API key here.
Example JavaScript Front-end
Tozny’s user-facing interface operates as a jQuery (JavaScript) plugin that pulls the push notification data or QR code from Tozny’s servers and handles the user session and login. Installing the Tozny jQuery plugin requires three steps:
- Include the remote JavaScript + CSS files. If your site already has jQuery imported, you do not need to include the jquery-1.10.2.min.js file.
<link rel="stylesheet" href="https://s3-us-west-2.amazonaws.com/tozny/production/interface/javascript/v2/tozny.css" type="text/css" media="all"> <script src="https://code.jquery.com/jquery-1.10.2.min.js"></script> <script src="https://s3-us-west-2.amazonaws.com/tozny/production/interface/javascript/v2/jquery.tozny.js"></script>
- Next, add the element where you want the Tozny login dialog to appear. It can appear anywhere on your page. For this example, we’ll add a div named tozny-login.
<div id=”tozny-login”></div>
- Finally, add the javascript to invoke the Tozny dialog in the element from Step #2. The javascript takes your realm’s key id (NOT your secret key) as a parameter.
$(document).ready(function() { $('#tozny-login').tozny(‘sid_123456789’); });
A minimalistic example of a complete Tozny front-end would simply be:
<!DOCTYPE html> <html lang="en"> <head> <title>Login</title> <link rel="stylesheet" href="https://s3-us-west-2.amazonaws.com/tozny/production/interface/javascript/v2/tozny.css" type="text/css" media="all" /> </head> <body> <div id="tozny-login"></div> <script src="https://code.jquery.com/jquery-1.10.2.min.js"></script> <script src="https://s3-us-west-2.amazonaws.com/tozny/production/interface/javascript/v2/jquery.tozny.js"></script> <script type="text/javascript"> $(document).ready(function() { $('#tozny-login').tozny("sid_52fa6d0a3a290"); }); </script> </body> </html>
You can see all this in action by visiting our demo.
Example Back-end
<?php
require 'ToznyRemoteRealmAPI.php';
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
if ($_REQUEST['tozny_action'] == 'tozny_login') {
if ($api->verifyLogin($_REQUEST['tozny_signed_data'], $_REQUEST['tozny_signature'])) {
// Successful Login
} else{
// Unsuccessful Login
}
}
require 'tozny/auth'
api = Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET')
if params[:tozny_action] == 'tozny_login'
user = tozny.check_login_locally(params[:tozny_signed_data], params[:tozny_signature])
if user and user.is_a?Hash
# Successful Login
else
# Unsuccessful Login
end
end
// There is no code example for this language.
# There is no code example for this language.
On the server side, you will need code to check the signature of the Tozny authentication payload. This cannot be done in JavaScript since it contains the secret API key as well as trusted authentication code. In this example, we use the Tozny SDK in several languages to check this signature.
The tozny_login
, tozny_signed_data
, and tozny_signature
are all form values written to the page by the Tozny JavaScript. They can be appended to a form you create, or the JavaScript can generate and submit its own form.
Identity Verification
Tozny supports verifying user email addresses as well as mobile phones through “magic links” and one-time-passwords over email and SMS.
E-Mail Address
Tozny offers email verification functionality that flows seamlessly into user enrollment and authentication. By generating a short-lived email challenge, often called a Magic Link, Tozny can take a user from on-boarding through to cryptographically secure, password-free login with minimal effort for the user.
Alternatively, Tozny can send a short-lived, 6-digit, one-time-password (OTP) to the user’s email. This code can be entered by the user and verified against a session to confirm a user’s email address. Both methods are described below.
Send Magic Link
// There is no code example for this language.
# There is no code example for this language.
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.LinkChallenge;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi realmApi = new RealmApi(config);
// generate link challenge to email to the user
String context = "verify";
Integer secondsValid = 300; // 5 minutes
String verificationEndpoint = "https://yoursite.com/verify";
boolean haveToznySendEmail = false;
LinkChallenge challenge = realmApi.linkChallenge("user@example.com", verificationEndpoint, secondsValid, context, haveToznySendEmail, null);
String magicLink = challenge.getUrl().toString();
System.out.println("Send this link via e-mail: " + magicLink);
# There is no code example for this language.
// Tozny mobile SDKs do not support magic link generation
// Tozny mobile SDKs do not support magic link generation
// Tozny mobile SDKs do not support magic link generation
The magic link would look something like this:
Send this link via e-mail: https://yoursite.com/verify?toznyo=c5a414fbeed42c59f374c1c1a40634f2&toznyr=YOUR-REALM-KEY-ID
- User enters their email into your application, which is then sent to your back-end for validation
- Use a Tozny back-end SDK (e.g. php, ruby, java, etc.) to generate a
LinkChallenge
for enrollment, formatting the challenge to point to your website- You can also enable your mobile app to capture this link to forward to your back-end
Verify Link
// There is no code example for this language.
# There is no code example for this language.
import com.tozny.sdk.UserApi;
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.user.Result;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi realmApi = new RealmApi(config);
UserApi userApi = new UserApi("YOUR-REALM-KEY-ID");
// one-time-password (OTP) collected from the user
// clicking the magic link to your endpoint
Result result = userApi.linkResult("OTP-FROM-YOUR-ENDPOINT");
// check for errors
if (result.isError()) {
// an error occurred
System.out.println("Error: " + result.getException().getMessage());
} else {
try {
// verify payload received from user OTP
String signedData = result.getSigned_data();
String signature = result.getSignature();
if (realmApi.verifyLogin(signedData, signature)) {
// email is verified
System.out.println("Email verified!");
}
}
catch (ToznyApiException e) { System.out.println("Error: " + e.getMessage()); }
}
# There is no code example for this language.
// Tozny mobile SDKs do not support magic link generation
// Tozny mobile SDKs do not support magic link generation
// Tozny mobile SDKs do not support magic link generation
Use the Tozny SDK to provide a link Result
or an error (e.g. link expired,
etc.). This completes the email verification.
Send One-Time-Password
// There is no code example for this language.
# There is no code example for this language.
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.OTPChallenge;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi realmApi = new RealmApi(config);
// use Tozny to send code to email
String type = "email";
String context = "verify";
OTPChallenge challenge = realmApi.otpChallenge(type, context, "user@example.com", null, null);
// 6-digit code sent to email,
// save session for later verification when user submits code
String session = challenge.getSessionId();
String presence = challenge.getPresence();
System.out.println("Can also repeat otpChallenge with generated presence: " + presence);
# There is no code example for this language.
#import <ToznyOTP.h>
// ...
// Tozny only allows mobile SDKs to generate one-time-passwords,
// which will be sent by the Tozny API. Your back-end may send "magic links"
[ToznyOTP generateOTP:ToznyOTPTypeEmail6
realmKeyID:@"YOUR-REALM-KEY-ID"
destination:@"user@example.com"
context:ToznyOTPContextVerify
apiHost:nil
completion:^(NSString * _Nullable sessionID, NSString * _Nullable presence, NSError * _Nullable error) {
if (error) { return NSLog(@"Error generating OTP"); }
// save session to verify later
NSLog(@"Session: %@ or Error: %@", sessionID, error);
}];
import ToznyCore
// ...
// Tozny only allows mobile SDKs to generate one-time-passwords,
// which will be sent by the Tozny API. Your back-end may send "magic links"
ToznyOTP.generateOTP(.Email6, realmKeyID: "YOUR-REALM-KEY-ID", destination: "user@example.com", context: .Verify, apiHost: nil) { (session, _, error) in
guard let sessionID = session else { return print("Error! \(error?.localizedDescription)") }
// save session to verify later
print("Session: \(sessionID)")
}
import com.tozny.sdk.*;
// ...
// Tozny only allows mobile SDKs to generate one-time-passwords,
// which will be sent by the Tozny API. Your back-end may send "magic links"
Tozny tozny = new Tozny("APP-CONTEXT-HERE");
tozny.generateOTP("YOUR-REALM-KEY-ID", ToznyOTPType.ToznyOTPTypeEmail6, "user@example.com", null, new GenerateOTPHandler() {
@Override
public void didGenerate(String sessionID, String presence) {
// save session to verify later
Log.d(TAG, "Session: " + sessionID);
}
@Override
public void didNotGenerate(ToznyException e) {
// error!
}
});
User enters their email into your application, which triggers Tozny to send a 6-digit code over email.
Verify OTP
// There is no code example for this language.
# There is no code example for this language.
import com.tozny.sdk.UserApi;
import com.tozny.sdk.RealmApi;
import com.tozny.sdk.user.Result;
import com.tozny.sdk.realm.RealmConfig;
import com.tozny.sdk.realm.config.ToznyRealmKeyId;
import com.tozny.sdk.realm.config.ToznyRealmSecret;
// ...
ToznyRealmKeyId realmKeyId = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig config = new RealmConfig(realmKeyId, realmSecret);
RealmApi realmApi = new RealmApi(config);
UserApi userApi = new UserApi("YOUR-REALM-KEY-ID")
// one-time-password (OTP) submitted by the user
Result result = userApi.otpResult("OTP-FROM-THE-USER");
// check for errors
if (result.isError()) {
// an error occurred
System.out.println("Error: " + result.getException().getMessage());
} else {
try {
// verify payload received from user OTP
String signedData = result.getSigned_data();
String signature = result.getSignature();
if (realmApi.verifyLogin(signedData, signature)) {
// email is verified
System.out.println("Email verified!");
}
}
catch (ToznyApiException e) {
// an error occurred
System.out.println("Error: " + e.getMessage());
}
}
# There is no code example for this language.
#import <ToznyOTP.h>
// ...
[ToznyOTP verifyOTP:@"OTP-FROM-USER"
realmKeyID:@"YOUR-REALM-KEY-ID"
sessionID:sessionID
apiHost:nil
completion:^(ToznyAuthentication * _Nullable authentication, NSError * _Nullable error) {
if (error) { return NSLog(@"Error verifying OTP"); }
// authentication received, send to back-end to verify signed data
NSLog(@"Authentication - signedPayload: %@ signature: %@", authentication.signedPayload, authentication.signature);
}];
import ToznyCore
// ...
ToznyOTP.verifyOTP("OTP-FROM-USER", realmKeyID: "YOUR-REALM-KEY-ID", sessionID: sessionID, apiHost: nil) { (authentication, error) in
guard let auth = authentication else { return print("Error verifying OTP \(error?.localizedDescription)") }
// authentication received, send to back-end to verify signed data
print("Authentication - signedPayload: \(auth.signedPayload) signature: \(auth.signature)")
}
import com.tozny.sdk.*;
// ...
// prompt the user to check their phone, then verify the OTP
String otp = getOTPFromUser();
Tozny tozny = new Tozny("APP-CONTEXT-HERE");
tozny.verifyOTP("YOUR-REALM-KEY-ID", otp, sessionID, null, new VerifyOTPHandler() {
@Override
public void didVerify(ToznyAuthentication auth) {
// authentication received, send to back-end to verify signed data
Log.d(TAG, "Authentication - signedPayload: " + auth.getSignedPayload() +
" signature: " + auth.getSignature());
}
@Override
public void didNotVerify(ToznyException e) {
// wrong OTP, or other error
}
});
Use the Tozny SDK to provide an OTP Result
(Authentication
) or an error
(e.g. link expired, etc.). Verify that the result signature matches the signed
data and this completes the email verification.
API Overview
Key Management
Before getting started, we assume you have completed the following:
- Installed the Tozny app on your phone. You can find them here.
- Created a Tozny account. You can create one here.
Getting your Tozny API Key
- Login to your Tozny account at https://admin.tozny.com.
- Navigate to the “Keys” area of your realm.
3. Click on the name of the key you want to use, or create a new one
4. Your key information will appear midway down the page. Your secret can be retrieved by clicking on the ‘view’ link.
Signed Data
Many Tozny API calls either accept or return a parameter called signed_data
. This is an arbitrary data element that takes the form of an encoded map - it’s a serialized, encoded object used to pass nested or multidimensional data in one pass.
Encoded Maps
While JSON supports simple data types as parameters, more complex items need to be encoded in such a way that they’re both concise and easy for the server to understand. These more complex datatypes utilize both JSON serialization and base64url encoding to encapsulate the data.
Base64url encoding is almost identical to base64 encoding - just remove any trailing =
, swap +
for -
, and swap /
for _
.
For example, the realm.user_add
function accepts an optional extra_fields
parameter for defining user meta. This could include:
- username
- birthdate
- phone number
To encode this information, you would first JSON serialize the map:
{"username":"testuser","email":"testuser@tozny.com","birthdate":"11-09-1983","phone":"+15555555555"}
Then, you would encode the serialized data as a base64url string.
eyJ1c2VybmFtZSI6InRlc3R1c2VyIiwiZW1haWwiOiJ0ZXN0dXNlckB0b3pueS5jb20iLCJiaXJ0aGRhdGUiOiIxMS0wOS0xOTgzIiwicGhvbmUiOiIrMTU1NTU1NTU1NTUifQ
The above example JSON has no spaces - trimming whitespace is not a requirement but made the example more concise. If the JSON string had spaces, its base64url-encoded equivalent would differ.
Signatures
#! /bin/bash
# Use Homebrew OpenSSL on Mac OS X if available.
if [ -x /usr/local/opt/openssl/bin/openssl ]; then
OPENSSL=/usr/local/opt/openssl/bin/openssl
else
OPENSSL=openssl
fi
# Base64URLEncode stdin to stdout.
function base64url()
{
base64 | tr "[+/]" "[\-_]" | sed -e 's/=*$//g'
}
# Sign stdin to stdout with HMAC key in "$1".
function sign_hmac()
{
$OPENSSL dgst -sha256 -hmac "$1" -binary | base64url
}
secret="YOUR-REALM-SECRET"
payload="{\"username\":\"testuser\",\"email\":\"testuser@tozny.com\",\"birthdate\":\"11-09-1983\",\"phone\":\"+15555555555\"}"
data=$(printf "$payload" | base64url)
signature=$(printf "$data" | sign_hmac "$secret")
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
class Main {
private static String base64url_encode(byte[] data) {
try {
return Base64.getUrlEncoder().withoutPadding().encodeToString(data);
} catch (Exception ex) {
return "";
}
}
private static String sign_hmac(byte[] data, String secret) {
try {
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);
return base64url_encode(sha256_HMAC.doFinal(data));
} catch (Exception ex) {
return "";
}
}
public static void main(String[] args) {
String secret = "YOUR-REALM-SECRET";
String payload = "{\"username\":\"testuser\",\"email\":\"testuser@tozny.com\",\"birthdate\":\"11-09-1983\",\"phone\":\"+15555555555\"}";
String data = base64url_encode(payload.getBytes());
String signature = sign_hmac(data.getBytes(), secret);
}
}
<?php
function base64url_encode( $data )
{
return rtrim( strtr( base64_encode( $data ), '+/', '-_' ), '=' );
}
function sign_hmac( $data, $secret )
{
return base64url_encode( hash_hmac( 'sha256', $data, $secret, true ) );
}
$secret = "YOUR-REALM-SECRET";
$payload = json_encode( ["username" => "testuser", "email" => "testuser@tozny.com", "birthdate" => "11-09-1983", "phone" => "+15555555555"] );
$data = base64url_encode( $payload );
$signature = sign_hmac( $data, $secret );
require 'openssl'
require 'base64'
require 'json'
def base64url_encode(data)
Base64::strict_encode64(data).tr('+/', '-_').tr('=', '')
end
def sign_hmac(data, secret)
base64url_encode(OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), secret, data))
end
secret = "YOUR-REALM-SECRET"
payload = {:username => "testuser", :email => "testuser@tozny.com", :birthdate => "11-09-1983", :phone => "+15555555555"}.to_json
data = base64url_encode(payload)
signature = sign_hmac(data, secret)
If a method requires a signature for the encoded payload, it will expect a base64url-encoded HMAC signature of the data using the Realm’s secret key as the signing key.
For example, given a Realm secret of cb0325c9dce8aad854c3f65d30420d1602ee4538419165f32ead9504702dbd54
, the signature on the payload above would be:
BxrVY8JRpApF_gD9dDDq1WtsgaTP55wKTYU8J8ChmUc
API Raw Calls
#! /bin/bash
# Use Homebrew OpenSSL on Mac OS X if available.
if [ -x /usr/local/opt/openssl/bin/openssl ]; then
OPENSSL=/usr/local/opt/openssl/bin/openssl
else
OPENSSL=openssl
fi
# Base64URLEncode stdin to stdout.
function base64url()
{
base64 | tr "[+/]" "[\-_]" | sed -e 's/=*$//g'
}
# Sign stdin to stdout with HMAC key in "$1".
function sign_hmac()
{
$OPENSSL dgst -sha256 -hmac "$1" -binary | base64url
}
# Generate a random nonce for the request
function generate_nonce()
{
$OPENSSL rand 16 | base64url
}
# Given a Realm Key ID and Secret, send a realm call
#
# Base64url-encoded data for first param and HMAC signature for second
function raw_call()
{
curl -s "https://api.tozny.com/index.php?signed_data=$1&signature=$2"
}
meta="{\"username\":\"testuser\",\"email\":\"testuser@tozny.com\"}"
encoded_meta=$(printf "$meta" | base64url)
key_id="YOUR_REALM_KEY_ID"
secret="YOUR_REALM_SECRET"
now=$(date +"%s")
expires=$((now + 300))
nonce=$(generate_nonce)
args="{\"nonce\":\"${nonce}\",\"expires_at\":\"${expires}\",\"realm_key_id\":\"${key_id}\",\"method\":\"realm.user_add\",\"defer\":\"true\",\"extra_fields\":\"${encoded_meta}\"}"
data=$(printf "$args" | base64url)
signature=$(printf "$data" | sign_hmac "$secret")
raw_call "$data" "$signature"
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;
import java.util.Map.Entry;
import java.io.*;
import java.security.SecureRandom;
import java.net.*;
class Main {
// Encode data for transmission
private static String base64url_encode(byte[] data) {
try {
return Base64.getUrlEncoder().withoutPadding().encodeToString(data);
} catch (Exception ex) {
return "";
}
}
// Encode and sign a string, returning a message map
private static Map<String, String> encode_and_sign(String json_data, String secret) {
String encoded_data = base64url_encode(json_data.getBytes());
String encoded_sig = "";
try {
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);
byte[] sig = sha256_HMAC.doFinal(encoded_data.getBytes());
encoded_sig = base64url_encode(sig);
} catch (Exception ex) {}
final String signature = encoded_sig;
return new HashMap<String, String>() {{
put("signed_data", encoded_data);
put("signature", signature);
}};
}
// Generate a random nonce for the request
private static String generate_nonce() {
byte[] bytes = new byte[16];
try {
SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
random.nextBytes(bytes);
} catch (Exception ex) {}
StringBuilder builder = new StringBuilder();
for (byte b : bytes) {
builder.append(String.format("%20x", b));
}
return builder.toString();
}
// Given a realm Key ID and Secret, send a realm call
private static InputStream raw_call(String realm_key_id, String realm_secret, Map<String, String> request) {
String args = "{\"nonce\":\"" + generate_nonce() + "\","
+ "\"expires_at\":\"" + ((int) (System.currentTimeMillis() / 1000L) + (5*60)) + "\","
+ "\"realm_key_id\":\"" + realm_key_id + "\"";
for(Entry<String, String> entry : request.entrySet()) {
args += ",\"" + entry.getKey() + "\":\"" + entry.getValue() + "\"";
}
args += "}";
Map<String, String> sig_arr = encode_and_sign(args, realm_secret);
String query;
try {
query = String.format(
"signed_data=%s&signature=%s",
(String) URLEncoder.encode(sig_arr.get("signed_data"), "UTF-8"),
(String) URLEncoder.encode(sig_arr.get("signature"), "UTF-8"));
} catch (Exception ex) {
query = "";
}
try {
URLConnection connection = new URL("https://api.tozny.com/index.php?" + query).openConnection();
connection.setRequestProperty("Accept-Charset", "UTF-8");
return connection.getInputStream();
} catch (Exception ex) {
return null;
}
}
public static void main(String[] args) {
// Set up an encoded map of user meta information
String meta = "{" +
"\"username\":\"testuser\"," +
"\"email\":\"testuser@tozny.com\"" +
"}";
String encoded_meta = base64url_encode(meta.getBytes());
// Make a realm.user_add call
Map<String, String> request = new HashMap<String, String>() {{
put("method", "realm.user_add");
put("defer", "true");
put("extra_fields", encoded_meta);
}};
InputStream response = raw_call("YOUR_REALM_KEY_ID", "YOUR_REALM_SECRET", request);
}
}
<?php
// Encode data for transmission
function _base64UrlEncode($data)
{
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
// Encode and sign a string, returning a message map
function _encodeAndSign($json_data, $secret)
{
$encoded_data = _base64UrlEncode($json_data);
$sig = hash_hmac('sha256', $encoded_data, $secret, true);
$encoded_sig = _base64UrlEncode($sig);
return [
'signed_data' => $encoded_data,
'signature' => $encoded_sig
];
}
// Generate a random nonce for the request
function _generateNonce()
{
return hash('sha256', openssl_random_pseudo_bytes(16));
}
// Given a Realm Key ID and Secret, send a realm call
function rawCall($realm_key_id, $realm_secret, array $args)
{
$args['nonce'] = _generateNonce();
$args['expires_at'] = time() + (5 * 60);
$args['realm_key_id'] = $realm_key_id;
$sigArr = _encodeAndSign(json_encode($args), $realm_secret);
$encodedResult = file_get_contents('https://api.tozny.com/index.php?' . http_build_query($sigArr));
return json_decode($encodedResult, true);
}
// Set up an encoded map of user meta information
$meta = [
'username' => 'testuser',
'email' => 'testuser@tozny.com',
];
$encoded_meta = _base64UrlEncode(json_encode($meta));
// Make a realm.user_add call
$args = [
'method' => 'realm.user_add',
'defer' => 'true',
'extra_fields' => $encoded_meta
];
$response = rawCall('YOUR_REALM_KEY_ID', 'YOUR_REALM_SECRET', $args);
require 'base64'
require 'json'
require 'net/http'
require 'openssl'
require 'securerandom'
require 'uri'
# Encode data for transmission
def _base64_url_encode(data)
Base64::strict_encode64(data).tr('+/', '-_').tr('=', '')
end
# Encode and sign a string, returning a message map
def _encode_and_sign(json_data, secret)
encoded_data = _base64_url_encode(json_data)
sig = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), secret, encoded_data)
encoded_sig = _base64_url_encode(sig)
{
signed_data: encoded_data,
signature: encoded_sig
}
end
# Generate a random nonce for the request
def _generate_nonce
OpenSSL::Digest::SHA256.hexdigest SecureRandom.random_bytes(16)
end
# Given a Realm Key ID and Secret, send a realm call
def raw_call(realm_key_id, realm_secret, request)
request[:nonce] = _generate_nonce
request[:expires_at] = Time.now.to_i + 5 * 60
request[:realm_key_id] = realm_key_id
sig_arr = _encode_and_sign(request.to_json, realm_secret)
request_url = URI.parse 'https://api.tozny.com/index.php'
request_url.query = URI.encode_www_form sig_arr
encoded_result = Net::HTTP.get(request_url)
JSON.parse(encoded_result, symbolize_names: true)
end
# Set up an encoded map of user meta information
meta = {
:username => "testuser",
:email => "testuser@tozny.com"
}
encoded_meta = _base64_url_encode meta.to_json
# Make a realm.user_add call
args = {
:method => "realm.user_add",
:defer => "true",
:extra_fields => encoded_meta
}
response = raw_call("YOUR_REALM_KEY_ID", "YOUR_REALM_SECRET", args)
While the Tozny SDKs attempt to provide abstractions for the most frequently-used and relevant API methods, there are some methods that aren’t yet supported by the SDKs directly. However, you can still make full use of the Tozny API by making a direct, raw call to the API itself.
Making a raw API call requires specifying: * The API method being invoked * The standard API parameters required for the method * Any encoded maps required for the method
API Reference: Realm Calls
realm.activity
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmActivity('sid_123456789', 'sid_345678912');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Lists the logged activities on a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | string | The unique ID of a user | |
activity | string | The type of activity to query | |
outcome | string | Expected query result (typically set to “all”) | |
realm_key_id_param | Only results using this realm_key_id | ||
user_key_id | string | A unique identifier mapped to a user’s public key | |
offset | int | The number of rows to skip in the query. Used to get entries past the limit. Overrides “page”. | |
rows | int | The number of rows to return in the query. Maximum is usually 100 | |
page | int | The virtual “page” of the results to return. eg, page 1 will return the first [rows] items, page 2 will return items [rows+1] to [2*rows] |
Return
Parameter | Type | Description |
---|---|---|
results | object | JSON object representing activity for a realm |
count | int | The number of results |
total | int | Also the number of results |
realm.check_valid_login
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
boolean validLogin = api.checkValidLogin("sid_123456789", "sessionid12345678901234567890");
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->checkValidLogin('sid_123456789', 'sessionid12345678901234567890', 1467739237);
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
validLogin = @realm.check_login_via_api('sid_123456789', 'sessionid12345678901234567890')
Checks if the user is logged in under the provided information
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
user_id | true | string | The unique ID of a user |
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
expires_at | true | int | The timestamp of when the session token expires |
session_id | true | string | A session ID of the format sid_************ |
Return
Parameter | Type | Description |
---|---|---|
result | bool | Flag whether or not the user is logged in |
user_id | string | The unique ID of the user |
realm.field_add
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->fieldAdd('Username', 'username', ['maps_to' => 'tozny_username']);
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Add a custom field to the realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
name | true | string | Human friendly name |
field | true | string | Machine friendly name |
description | string | A description of the field | |
maps_to | string | The TOZNY internal realm property the field maps to. Valid options are ints 0-4, mapped as follows, respectively: NULL, tozny_username, tozny_email, tozny_birthdate, tozny_display_name | |
required | int | 1 or 0. Whether or not the field is required | |
uniq | int | 1 or 0. Whether or not this field is unique | |
searchable | int | 1 or 0. Whether or not this field should be indexed on searches | |
encrypted | int | 1 or 0. Whether or not this field should be encrypted | |
primary_view | int | 1 or 0. Whether or not we should display this in the primary identifier of a user in the Tozny system | |
secondary_view | int | 1 or 0. Whether or not we should display this in the secondary identifier of a user in the Tozny system |
Return
Parameter | Type | Description |
---|---|---|
realm_key_id | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
field_id | string | An identifier unique to each field |
results | object | JSON representation of the created field |
realm.field_delete
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->fieldDelete('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Deletes a field from a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
field_id | true | string | ID of the field to delete. |
Return
Parameter | Type | Description |
---|---|---|
field_id | string | Deleted field ID |
results | array | Deleted field ID |
realm.field_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->fieldGet('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Gets all available fields for a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
field_id | true | string | ID of the field to retrieve |
Return
Parameter | Type | Description |
---|---|---|
field_id | string | ID of the field that was retrieved |
results | object | JSON object representing the retrieved field |
realm.field_update
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->fieldUpdate('sid_123456789', ['name' => 'Updated Username']);
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Update a custom field for a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
field_id | true | string | An identifier unique to each field |
name | string | Human friendly name | |
field | string | Machine friendly name | |
description | string | A description of the field | |
maps_to | string | The Tozny internal realm property the field maps to. Valid options are ints 0-4, mapped as follows, respectively: NULL, tozny_username, tozny_email, tozny_birthdate, tozny_display_name | |
required | int | 1 or 0. Whether or not the field is required | |
uniq | int | 1 or 0. Whether or not this field is unique | |
searchable | int | 1 or 0. Whether or not this field should be indexed on searches | |
encrypted | int | 1 or 0. Whether or not this field should be encrypted | |
primary_view | int | 1 or 0. Whether or not we should display this in the primary identifier of a user in the tozny system | |
secondary_view | int | 1 or 0. Whether or not we should display this in the secondary identifier of a user in the tozny system |
Return
Parameter | Type | Description |
---|---|---|
results | object | JSON representation of the updated field |
realm_key_id | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
field_id | string | ID of the updated field |
realm.fields_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->fieldsGet();
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Gets all the available fields of a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
field_ids | string | Comma-separated list of fields to retrieve. | |
offset | int | The number of rows to skip in the query. Used to get entries past the limit. Overrides “page”. | |
rows | int | The number of rows to return in the query. Maximum is usually 100 | |
page | int | The virtual “page” of the results to return. eg, page 1 will return the first [rows] items, page 2 will return items [rows+1] to [2*rows] | |
term | string | A search term |
Return
Parameter | Type | Description |
---|---|---|
results | object | JSON object representing retrieved fields |
count | int | The number of results |
total | int | Also the number of results |
realm.key_add
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmKeyAdd('New Realm Key Description');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Create a key to a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
name | true | string | Human friendly name |
Return
Parameter | Type | Description |
---|---|---|
name | string | Human friendly key name |
key_id | string | The ID of the Realm’s new key |
secret_key | string | The newly-generated secret key |
realm.key_delete
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmKeyDelete('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Deletes a realm key based on the key_id
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The ID of the Realm key used to sign the request |
key_id | true | string | The ID of the Realm key to delete |
Return
Parameter | Type | Description |
---|---|---|
bool | True if successful, false on failure |
realm.key_exists
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmKeyExists('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Determine whether the realm_key referred to exists
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
key_id | true | string | ID of the Realm key to verify |
Return
Parameter | Type | Description |
---|---|---|
return | bool | Whether or not the key exists |
key_id | string | ID of the Realm key queried |
realm.key_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmKeyGet('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Get the details of a realm key
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
key_id | true | string | ID of the Realm key to query |
Return
Parameter | Type | Description |
---|---|---|
name | string | Human-readable name |
key_id | string | ID of the Realm key queried |
secret_key | string | Secret key |
total_logins | int | The number of logins to the realm. |
total_failed_logins | int | The number of unsuccessful logins to the realm |
last_login | int | The last login to the realm |
last_failed_login | int | The last unsuccessful login to the realm |
realm.key_update
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmKeyUpdate('sid_123456789', 'New Realm Key Description', true);
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Generates a new realm key, optionally deleting the old one.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
key_id | true | string | ID of the Realm key to update |
name | string | Human friendly name | |
roll_secret_key | string | Literal “true” to remove the old Realm key |
Return
Parameter | Type | Description |
---|---|---|
name | string | Human friendly name |
key_id | string | ID of the updated Realm key |
secret_key | string | Secret key |
realm.keys_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmKeysGet(['sid_123456789']);
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Retrieve the information of all keys for a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
key_id | string | Comma-separated list of Realm keys to query | |
rows | int | The number of rows to return in the query. Maximum is usually 100 | |
offset | int | The number of rows to skip in the query. Used to get entries past the limit. Overrides “page”. | |
page | int | The virtual “page” of the results to return. eg, page 1 will return the first [rows] items, page 2 will return items [rows+1] to [2*rows] | |
term | string | A search term |
Return
Parameter | Type | Description |
---|---|---|
results | object | JSON object (associative array, indexed by Realm key IDs) of all key representations |
count | int | The number of results |
realm.link_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
LinkChallenge challenge = api.linkChallenge("+15555555555", "https://handler.yoursite.com/", 500, "enroll", true, null);
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmLinkChallenge('+15555555555', 'https://handler.yoursite.com/', 500, 'enroll');
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
response = @realm.link_challenge('+15555555555', 'https://handler.yoursite.com/', 500, 'enroll')
Deliver a one-time-password challenge as a magic link via SMS or e-mail.
If the optional “send” parameter is set to a literal “no,” then the magic link will not be sent automatically by Tozny but instead returned as a field in the response. It is up to the relying party to send the link to the customer to complete a session.
The endpoint provided should direct to the relying party’s server in such a way as the magic link’s embedded one-time-password can be forwarded to Tozny via a user.link_result
call.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
destination | true | string | Phone number or e-mail address. |
endpoint | true | string | Base URL from which Tozny should generate the magic link. |
lifespan | int | Number of seconds for which the link will be valid. Default is 300 (5 minutes). | |
context | string | One of “enroll,” “authenticate,” or “verify”. | |
send | string | Either “yes” or “no” - “no” will return the magic link rather than sending an email/SMS. | |
data | string | Realm-specific data to add to the signed response on success. |
Return
Parameter | Type | Description |
---|---|---|
realm_key_id | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
session_id | string | The unique session identifier |
created_at | int | Timestamp for when When the challenge was created; used for session validation |
presence | string | The device’s identifier, used to cache the identity of a client across sessions to allow for a smoother user experience |
url | string | Actual magic link - only returned if “send” was set to “no” in the original request |
realm.otp_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
OTPChallenge challenge = api.otpChallenge("sms-otp-6", "enroll", "+15555555555", null, null);
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmOTPChallenge('presence1234567890', 'sms-otp-6', '+15555555555', null, 'enroll');
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
response = @realm.otp_challenge('sms-otp-6', '+15555555555', nil, nil, 'enroll')
Deliver a one-time-password challenge via SMS or e-mail.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
type | string | The format and mechanism used to send the one-time password (one of sms-otp-6 , sms-otp-8 , or email ) |
|
destination | string | Phone number or e-mail address based on type |
|
presence | string | If defined, re-use a previously used format and destination | |
data | string | Realm-specific data to add to the signed response on success |
Return
Parameter | Type | Description |
---|---|---|
realm_key_id | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
session_id | string | The unique session identifier |
created_at | int | Timestamp for when When the challenge was created; used for session validation |
presence | string | The device’s identifier, used to cache the identity of a client across sessions to allow for a smoother user experience |
realm.question_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
Session challengeSession = api.questionChallenge("Do you confirm a $100 transfer?", "sid_12345789");
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->questionChallenge('Do you confirm a $100 transfer?', 'sid_123456789');
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
challengeSession = @realm.question_challenge('Do you confirm a $100 transfer?', nil, nil, 'sid_123456789')
Generate an OOB question challenge session
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
question | true | string | Question to prompt |
user_id | string | The unique ID of the user to prompt |
Return
Parameter | Type | Description |
---|---|---|
challenge | string | The challenge to be signed by the user |
session_id | string | The unique session identifier |
realm_key_id | string | ID of the Realm key used to sign the request |
qr_url | string | A link to the QR code to display to the user |
mobile_url | string | A tozauth URL which can be handled by the Tozny apps |
created_at | int | When the challenge was created at, used for session validation |
presence | string | The device’s identifier, used to cache the identity of a client across sessions to allow for a smoother user experience |
realm.realm_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmGet();
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Returns the information of a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
Return
Parameter | Type | Description |
---|---|---|
realm_id | string | ID of the retrieved Realm |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
display_name | string | Human-readable name describing this realm |
open_enrollment | string | Whether or not the realm supports open enrollment |
crypto_suite | string | The crypto suite used in the realm. |
domain | string | The domain associated with the realm. |
ip_address | string | The IP address associated with the realm. |
total_users | int | The number of users currently registered to the realm |
total_keys | int | The number of keys registered to the realm |
total_postbacks | int | The number of postbacks sent by the realm |
total_fields | int | The number of custom fields implemented in the realm’s database. |
total_logins | int | The number of logins to the realm. |
total_devices | int | The number of devices registered to the realm |
total_failed_logins | int | The number of unsuccessful logins to the realm |
last_login | int | The last login to the realm |
last_failed_login | int | The last unsuccessful login to the realm |
allow_user_key_backup | string | Unimplemented. Whether or not the user should be allowed to backup their secret key |
APNS_push_key_desc | string | A human-readable description of the APNS push key/cert |
APNS_SANDBOX_push_key_desc | string | Description of the APNS sandbox push key/cert |
GCM_key_desc | string | A human-readable description of the GCM push key |
sms_otp_enabled | string | Whether unauthenticated one-time-password generation and transmission is allowed |
realm.realm_update
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmUpdate(['display_name' => 'New Display Name']);
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Update the settings of the realm.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
open_enrollment | string | Whether or not the realm supports/should support open enrollment | |
display_name | string | Human-readable name describing this realm | |
ip_address | string | The IP address associated with the realm. | |
domain | string | The domain associated with the realm. | |
logo_url | string | Logo in the app for users | |
info_url | string | URL in the app for users | |
package_id | string | The package registered to this realm | |
APNS_push_cert | string | The apple certificate used to enable push notification | |
APNS_push_key_desc | string | A human-readable description of the APNS push key/cert | |
APNS_push_key | string | The RSA key used to authenticate to APNS | |
APNS_SANDBOX_push_cert | string | Apple sandbox push certificate | |
APNS_SANDBOX_push_key_desc | string | Human-readable description of the APNS sandbox certificate | |
APNS_SANDBOX_push_key | string | The RSA key used to authenticate against the APNS sandbox | |
GCM_push_key | string | The Google push authentication key | |
GCM_key_desc | string | A human-readable description of the GCM push key | |
sms_otp_enabled | string | A flag to allow unauthenticated one-time-password generation and transmission |
Return
Parameter | Type | Description |
---|---|---|
realm_id | string | An identifier unique to the realm. There is only one of these per realm. |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
display_name | string | Human-readable name describing this realm |
open_enrollment | string | Whether or not the realm supports open enrollment |
crypto_suite | string | The crypto suite used in the realm. |
domain | string | The domain associated with the realm. |
ip_address | string | Unimplemented. The IP address associated with the realm. |
package_id | string | The TOZNY billing plan (secure, professional, etc) associated with this realm. |
total_logins | int | The number of logins to the realm. |
total_keys | int | The number of keys registered to the realm |
APNS_push_key_desc | string | A human-readable description of the APNS push key/cert |
APNS_SANDBOX_push_key_desc | string | Description of the APNS sandbox push key/cert |
GCM_key_desc | string | A human-readable description of the GCM push key |
sms_otp_enabled | string | A flag to allow unauthenticated one-time-password generation and transmission |
realm.user_add
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
UserAddResponse response = api.userAdd(true, null);
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->userAdd('true', array(), null);
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
@realm.user_add('true', nil, nil)
Adds a user, signed by the realm_key so valid for closed enrollment. If deferred, requires user.user_add_complete to be called later.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
defer | true | string | A string ‘true’ or 'false’ representing whether or not to defer enrollment. If 'true’, user.user_add_complete will need to be called to complete enrollment. |
extra_fields | encoded map | All the additional fields like username, email, birthdate, favorite color, etc. | |
pub_key | ? | string | The user’s public RSA key. REQUIRED if defer is "false" |
Return
Parameter | Type | Description |
---|---|---|
username | string | The username of the current user. |
user_id | string | An identifier unique to the user. There is only one of these per user. |
user_temp_key | string | A temporary key assigned to the user to be replaced with a permanent key. |
secret_enrollment_url | string | A tozauth URL containing the challenge, user_temp_key, and realm information necessary to complete registration |
secret_enrollment_qr_url | string | A link to a QR code containing a secret_enrollment_url |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
crypto_suite | string | The crypto suite used in the realm. |
display_name | string | Human-readable name describing this (user |
realm.user_delete
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->userDelete('sid_123456789');
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
@realm.user_delete('sid_123456789')
Removes a user from a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | true | string | The unique ID of a user |
Return
Parameter | Type | Description |
---|---|---|
realm_key_id | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
deleted_user_id | string | The ID of the deleted user |
realm.user_device_add
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
UserDeviceAddResponse response = api.userDeviceAdd("sid_123456789");
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $apu->realmUserDeviceAdd("sid_1234567");
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
response = @realm.user_device_add('sid_123456789')
Register a new device to the user. This creates a new key slot, temp key, and enrollment URL, as in deferred enrollment. Also like deferred enrollment, call user.user_add_complete afterwards.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | true | string | The unique ID of a user |
Return
Parameter | Type | Description |
---|---|---|
user_id | string | An identifier unique to the user. There is only one of these per user. |
temp_key | string | A temporary key assigned to the user to be replaced with a permanent key. |
secret_enrollment_url | string | A tozauth URL containing the challenge, user_temp_key, and realm information necessary to complete registration |
secret_enrollment_qr_url | string | A link to a QR code containing a secret_enrollment_url |
key_id | string | A realm_key_id |
created | int | Timestamp from when the device whas added |
status | string | Device status |
realm.user_device_delete
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmUserDeviceDelete('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Delete a key_id (aka a device) from a user’s account for a realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_key_id | true | string | A unique identifier mapped to a user’s public key |
Return
Parameter | Type | Description |
---|---|---|
user_id | string | An identifier unique to the user. There is only one of these per user. |
deleted_user_key_id | string | User key ID from the deleted device |
realm.user_device_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmUserDeviceGet('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Gets a user_key based on its ID and the realm with which it is associated. If a temp_key
is still set in the database, a collection of enrollment URLs will be returned to allow for the addition of a new device.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_key_id | true | string | A unique identifier mapped to a user’s public key |
Return
Parameter | Type | Description |
---|---|---|
secret_enrollment_url | string | URL for adding a new device |
secret_enrollment_qr_url | string | URL for the QR code embedding the enrollment URL |
realm_key_id | string | Identifier of the Realm in use |
realm.user_device_update
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmUserDeviceUpdate('sid_123456789', 'New Android Device');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Update the device description for a given user_key_id (aka device)
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_key_id | true | string | A unique identifier mapped to a user’s public key |
device_description | true | string | Description of device |
Return
Parameter | Type | Description |
---|---|---|
results | object | JSON object representation of the stored key |
realm.user_devices
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->realmUserDevices('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Retrieves the devices associated with the user on the given realm.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | true | string | The unique ID of a user |
rows | int | The number of rows to return in the query. Maximum is usually 100 | |
offset | int | The number of rows to skip in the query. Used to get entries past the limit. Overrides “page”. | |
page | int | The virtual “page” of the results to return. eg, page 1 will return the first [rows] items, page 2 will return items [rows+1] to [2*rows] | |
term | string | A search term |
Return
Parameter | Type | Description |
---|---|---|
results | object | JSON collection of all user device keys |
count | int | The number of results |
total | int | Also the number of results |
realm.user_exists
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
boolean userExists = api.userExists("sid_123456789");
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->userExists('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Returns the user_id the first user found matching the provided information.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | string | The unique ID of a user | |
tozny_email | string | Distinguished email address of the user | |
tozny_username | string | Distinguished username of the user | |
user_key_id | string | A unique identifier mapped to a user’s public key |
Return
Parameter | Type | Description |
---|---|---|
return | string | String literal ‘true’ or 'false’ |
user_id | string | ID of the user queried |
realm.user_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
User user = api.userGet("sid_123456789");
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->userGet('sid_123456789');
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
user = @realm.user_get('sid_123456789')
Gets the information of a user - either the user’s ID or email address must be specified.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | string | The unique ID of a user | |
tozny_email | string | Distinguished user email address |
Return
Parameter | Type | Description |
---|---|---|
results | object | JSON object representation of the user |
user_id | string | An identifier unique to the user. There is only one of these per user. |
realm.user_get_id
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->UserGetId('sid_123456789');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Retrieves a user ID given their device/key ID.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_key_id | true | string | A unique identifier mapped to a user’s public key |
Return
Parameter | Type | Description |
---|---|---|
user_id | string | An identifier unique to the user. There is only one of these per user. |
realm.user_push
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
// There is no PHP SDK available for this method.
// Please see our API Raw Call documentation instead.
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
response = @realm.user_push('sessionid12345678901234567890', 'sid_123456789')
Push a notification (for authentication) to a user device. At least one of user_id
, tozny_email
, or tozny_username
must be specified.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | string | The unique ID of a user | |
tozny_email | string | Distinguished email address of the user | |
tozny_username | string | Distinguished username of the user | |
session_id | true | string | A session ID of the format sid_************ |
Return
Parameter | Type | Description |
---|---|---|
results | bool | Whether or not the push was successful |
realm.user_update
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->userUpdate('sid_123456789', ['username' => 'testuser']);
@realm = ::Tozny::Realm.new('YOUR-REALM-KEY-ID', 'YOUR-REALM-SECRET', 'https://api.tozny.com')
@realm.user_update('sid_123456789', {:username => 'testuser'})
Updates the user’s metadata.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
user_id | true | string | The unique ID of a user |
extra_fields | true | encoded map | All the additional fields like username, email, birthdate, favorite color, etc. |
Return
Parameter | Type | Description |
---|---|---|
username | string | The username of the current user. |
user_id | string | An identifier unique to the user. There is only one of these per user. |
user_temp_key | string | A temporary key assigned to the user to be replaced with a permanent key. |
secret_enrollment_url | string | A tozauth URL containing the challenge, user_temp_key, and realm information necessary to complete registration |
secret_enrollment_qr_url | string | A link to a QR code containing a secret_enrollment_url |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
crypto_suite | string | The crypto suite used in the realm. |
display_name | string | Human-readable name describing this user |
realm.users_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
ToznyRealmKeyId realmKey = new ToznyRealmKeyId("YOUR-REALM-KEY-ID");
ToznyRealmSecret realmSecret = new ToznyRealmSecret("YOUR-REALM-SECRET");
RealmConfig realmConfig = new RealmConfig(realmKey, RealmSecret);
RealmApi api = new RealmApi(realmConfig);
Map<String,User> users = api.usersGet(null, null, Arrays.asList("sid_123456789", "sid_987654321"), 2);
<?php
$api = new Tozny_Remote_Realm_API("YOUR-REALM-KEY-ID", "YOUR-REALM-SECRET", "https://api.tozny.com");
$response = $api->usersGet(null, null, null, null, null, ['sid_123456789', 'sid_987654321'], 2);
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Gets the information of users for the realm
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | An identifier unique to each realm_secret. There can be multiple of these per realm. | |
term | A search term | ||
meta_advanced | encoded map | Optional, additional search terms | |
meta_fields | string | Comma-separated list of fields to retrieve | |
tozny_advanced | encoded map | Optional, additional distinguished search terms | |
tozny_fields | string | Comma-separated list of fields to retrieve | |
user_ids | string | Comma-separated list of user IDs to retrieve | |
rows | int | The number of rows to return in the query. Maximum is usually 100 | |
offset | int | The number of rows to skip in the query. Used to get entries past the limit. Overrides “page”. | |
page | int | The virtual “page” of the results to return. eg, page 1 will return the first [rows] items, page 2 will return items [rows+1] to [2*rows] |
Return
Parameter | Type | Description |
---|---|---|
results | array | Collection of JSON object representations of users |
count | int | The number of results |
total | int | Also the number of results |
API Reference: User Calls
user.challenge_exchange
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
UserApi api = new UserApi("https://api.tozny.com", "YOUR-REALM-KEY-ID");
EnrollmentChallenge challenge = api.enrollmentChallengeExchange("signeddata12345678901234567890", "signature12345678901234567890");
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->userChallengeExchange('signeddata12345678901234567890', 'signature12345678901234567890');
@user = ::Tozny::User.new('YOUR-REALM-KEY-ID', 'https://api.tozny.com')
challenge = @user.challenge_exchange('signeddata12345678901234567890', 'signature12345678901234567890');
Exchange a signed OTP or magic link session for an authentication or enrollment challenge (depending on the original “context” value used to create the challenge).
If the OTP is being used to validate user authentication, the ID of that user’s authentication session can be passed as a third parameter and will be automatically completed within the API. Subsequent user.check_session_status
calls will then indicate a completed session.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
signed_data | true | string | Encoded map defining the OTP session that has been completed |
signature | true | string | Realm-signed signature of the above data |
session_id | string | Optional authentication session identifier |
Return
In the case of an “authentication” context, this method will return:
Parameter | Type | Description |
---|---|---|
signed_data | string | Encoded map representing the user that has been authenticated |
signature | string | Realm-signed signature of the above data |
In the case of an “enroll” context, this method will return:
Parameter | Type | Description |
---|---|---|
user_id | string | An identifier unique to the user. There is only one of these per user. |
temp_key | string | A temporary key assigned to the user to be replaced with a permanent key. |
key_id | string | ID of the device/key being added for the user |
secret_enrollment_url | string | A tozauth URL containing the challenge, user_temp_key, and realm information necessary to complete registration |
secret_enrollment_qr_url | string | A link to a QR code containing a secret_enrollment_url |
created | string | Time when the user’s device was created |
status | string | Status of the user’s device in the system |
In the case of a “verify” context, this method will return an error.
user.check_enrollment_status
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
// There is no PHP SDK available for this method.
// Please see our API Raw Call documentation instead.
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Checks whether or not a user with deferred enrollment has finished registering.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
user_temp_key | true | string | The temp_key provided by a deferred enrollment request |
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
Return
Parameter | Type | Description |
---|---|---|
status | string | Either “complete” or “pending” |
user.check_session_status
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->checkSessionStatus('sessionid12345678901234567890');
@user = ::Tozny::User.new('YOUR-REALM-KEY-ID', 'https://api.tozny.com')
response = @user.check_session_status('sessionid12345678901234567890')
Checks the status of a status. If the session is a question, return the answer.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
session_id | true | string | A session ID of the format sid_************ |
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
Return
Parameter | Type | Description |
---|---|---|
signed_data | string | The base64URL-encoded payload to be mirrored to the server or the RP containing the user information and/or the question and answer |
signature | string | The signature of signed_data |
status | string | The status of the session, usually “pending” if the challenge is not complete. If this is present, there will be no signed_data or signature |
user.link_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
UserApi api = new UserApi("https://api.tozny.com", "YOUR-REALM-KEY-ID");
Challenge challenge = api.linkChallenge("+15555555555", "https://handler.yoursite.com/", "enroll");
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->userLinkChallenge('+15555555555', 'https://handler.yoursite.com/', 'enroll');
@user = ::Tozny::User.new('YOUR-REALM-KEY-ID', 'https://api.tozny.com')
response = @user.link_challenge('+15555555555', 'https://handler.yoursite.com/', 'enroll')
Deliver a one-time-password challenge as a magic link via SMS or e-mail.
Unlike this method’s Realm counterpart, every invocation will send by default. In addition, unauthenticated magic links must be explicitly enabled in the admin panel or any invocations will fail.
The endpoint provided should direct to the relying party’s server in such a way as the magic link’s embedded one-time-password can be forwarded to Tozny via a user.link_result
call.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | ID of the Realm key used to sign the request |
destination | true | string | Phone number or e-mail address. |
endpoint | true | string | Base URL from which Tozny should generate the magic link. |
context | string | One of “enroll,” “authenticate,” or “verify”. |
Return
Parameter | Type | Description |
---|---|---|
realm_key_id | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
session_id | string | The unique session identifier |
created_at | int | Timestamp for when When the challenge was created; used for session validation |
presence | string | The device’s identifier, used to cache the identity of a client across sessions to allow for a smoother user experience |
user.link_result
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
UserApi api = new UserApi("https://api.tozny.com", "YOUR-REALM-KEY-ID");
Result linkResult = api.linkResult("abcdefghijklmnopqr123456");
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->userLinkResult('abcdefghijklmnopqr123456');
@user = ::Tozny::User.new('YOUR-REALM-KEY-ID', 'https://api.tozny.com')
sessionData = @user.link_result('abcdefghijklmnopqr123456')
Validate an OTP embedded in a magic link and create an OTP presence for it
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
otp | true | string | The OTP to validate. |
Return
Parameter | Type | Description |
---|---|---|
signed_data | string | The base64URL-encoded payload to containing the phone verification information, including a session ID and metadata, if any |
signature | string | The signature of signed_data |
user.login_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->loginChallenge();
@user = ::Tozny::User.new('YOUR-REALM-KEY-ID', 'https://api.tozny.com')
loginChallenge = @user.login_challenge(true)
Create a session and a challenge code with which a user can log in.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
user_add | string | Literal “true” or “false.” If defined, will create an add request in the URL and QR response. |
|
format | string | The format to return the challenge in. Use ‘qr’ to generate a QR code. |
Return
Parameter | Type | Description |
---|---|---|
challenge | string | The challenge to be signed by the user. |
realm_key_id | string | An identifier unique to each realm_secret. There can be multiple of these per realm. |
session_id | string | The unique session identifier. |
qr_url | string | A link to the QR code to display to the user. |
mobile_url | string | A tozauth:// URL which can be handled by the Tozny apps. |
created_at | int | When the challenge was created at, used for session validation. |
presence | string | The device’s identifier; used to cache the identity of a client across sessions to allow for a smoother user experience. |
user.login_result
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->loginResult(['user_id' => 'sid_123456789', 'user_key_id' => 'sid_456789123']);
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
After creating a challenge with user.login_challenge
, combine the challenge with the user’s key to log them in.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
session_id | true | string | A session ID of the format sid_************ |
response | true | string | A JSON object containing an RSA ‘signature’ of signed_data and 'signed_data’ containing a base64URL-encoded JSON object containing fields 'nonce’, 'expires_at’, 'session_id’, and 'challenge’ |
user_key_id | true | string | A unique identifier mapped to a user’s public key |
user_id | true | string | The unique ID of a user |
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
push_token | string | The push token of the user’s mobile device | |
push_platform | string | A string identifying the platform of the user’s device. One of 'apns’, 'apns_sandbox’, or 'gcm’ | |
login_type | string | Should always be “RSA”. If it’s not, use user.rotate_key to get an RSA key | |
remote_lat | string | Geographic latitude of device. Will be used as an additional security factor. | |
remote_long | string | Geographic longitude of device. Will be used as an additional security factor. |
Return
Parameter | Type | Description |
---|---|---|
signed_data | string | The base64URL-encoded payload to be mirrored to the server or the RP containing the user information and/or the question and answer |
signature | string | The signature of signed_data |
user.otp_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
UserApi api = new UserApi("https://api.tozny.com", "YOUR-REALM-KEY-ID");
Challenge challenge = api.otpChallenge("+15555555555", "sms-otp-6", "authenticate");
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->userOTPChallenge(null, 'sms-otp-6', '+15555555555', 'authenticate');
@user = ::Tozny::User.new('YOUR-REALM-KEY-ID', 'https://api.tozny.com')
challengeSession = @user.otp_challenge('sms-otp-6', '+15555555555', nil, 'authenticate')
Deliver a one-time-password challenge via SMS, text-to-speech, or e-mail.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
type | string | The format and mecnahism used to send the one-time password | |
context | string | One of “enroll,” “authenticate,” or “verify.” | |
destination | string | Phone number or e-mail address based on ‘type’. | |
presence | string | If defined, re-use a previousl-used format and destination |
Return
Parameter | Type | Description |
---|---|---|
realm_key_id | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
session_id | string | The unique session identifier |
created_at | int | When the OTP challenge was created at, used for session validation |
presence | string | The device’s identifier, used to cache the identity of a client across sessions to allow for a smoother user experience |
user.otp_result
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
UserApi api = new UserApi("https://api.tozny.com", "YOUR-REALM-KEY-ID");
Result otpResult = api.otpResult("123456", "sessionid12345678901234567890");
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->userOTPResult('sessionid12345678901234567890', '123456');
@user = ::Tozny::User.new('YOUR-REALM-KEY-ID', 'https://api.tozny.com')
sessionData = @user.otp_result('sessionid12345678901234567890', '123456')
Validate an OTP against a session token and create an OTP presence for it
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
session_id | true | string | A session ID of the format sid_************ |
otp | true | string | The OTP to validate against the session. |
Return
Parameter | Type | Description |
---|---|---|
signed_data | string | The base64URL-encoded payload to containing the phone verification information, including a session ID and metadata, if any |
signature | string | The signature of signed_data |
user.push
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
// There is no PHP SDK available for this method.
// Please see our API Raw Call documentation instead.
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Sends a push notification to the registered presence, using the session_id for verification
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
session_id | true | string | A session ID of the format sid_************ |
presence | true | string | The presence token to send the push notification to |
Return
Parameter | Type | Description |
---|---|---|
results | array | Array-wrapped Boolean flag representing whether or not the push was successful |
user.qr_add_complete
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->qrAddComplete('user_temp_key...');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Gets a QR code that can be used to complete enrollment.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
user_temp_key | true | string | The temporary key provided by a deferred enrollment request. |
Return
Parameter | Type | Description |
---|---|---|
photo | string | URL to a PNG image of the QR code. |
user.qr_login_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->qrLoginChallenge();
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Gets a QR code that represents a login challenge.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
challenge | true | string | The challenge to be presented to the user. |
session_id | true | string | A session ID of the format sid_************. |
created_at | int | The time at which the challenge was created. | |
q | string | Whether or not the challenge should be a question challenge. | |
user_add | string | Literal “true” or “false” to flag whether or not the user should also be enrolled. |
Return
Parameter | Type | Description |
---|---|---|
photo | string | URL to a PNG image of the QR code. |
user.qr_question_challenge
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
// There is no PHP SDK available for this method.
// Please see our API Raw Call documentation instead.
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Generates a QR code to represent an out-of-band (OOB) question challenge session.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
challenge | true | string | The challenge to be presented to the user. |
session_id | true | string | A session ID of the format sid_************. |
user_add | string | Literal “true” or “false” to flag whether or not the user should also be enrolled. | |
created_at | int | The time at which the challenge was created. |
Return
Parameter | Type | Description |
---|---|---|
photo | string | URL to a PNG image of the QR code. |
user.question_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->questionGet('sessionid12345678901234567890');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Gets the plaintext out-of-band (OOB) question.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | AThe unique identifier for a Realm’s key (There can be multiple of these per Realm). |
session_id | true | string | A session ID of the format sid_************. |
Return
Parameter | Type | Description |
---|---|---|
type | string | The type of question. |
question | string | The OOB question (in an array) to present to the user, or [false] if this is not a question session. |
user.question_result
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$user = [
'user_id' => 'sid_123456789',
'user_key_id' => 'sid_456789123',
'user_secret' => 'RSA Private Key...',
];
$challenge = [
'session_id' => 'sessionid12345678901234567890',
'challenge' => '12345678901234567890',
];
$response = $api->questionResultRaw($user, $challenge, 'answertoquestion');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Attempts to send an answer and requests verification based on the challenge, as with user.login_result
.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
session_id | true | string | A session ID of the format sid_************. |
response | true | object | A JSON object containing an RSA ‘signature’ of signed_data and 'signed_data’ containing a base64URL-encoded JSON object containing fields 'nonce’, 'expires_at’, 'session_id’, and 'challenge’. |
user_key_id | true | string | A unique identifier mapped to a user’s public key. |
user_id | true | string | The unique ID of a user. |
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
answer | true | string | The answer to the question displayed to the user: if the session is verified as coming from the user, this will be signed and mirrored so that it can be sent to the realm. |
push_token | string | The push token of the user’s mobile device. | |
push_platform | string | A string identifying the platform of the user’s device. One of 'apns’, 'apns_sandbox’, or 'gcm’. | |
login_type | string | Should always be “RSA”. If it’s not, use user.rotate_key to get an RSA key. | |
remote_lat | string | Geographic latitude of device. Will be used as an additional security factor. | |
remote_long | string | Geographic longitude of device. Will be used as an additional security factor. |
Return
Parameter | Type | Description |
---|---|---|
signed_data | string | A realm-signed payload containing the method, meta, user_id, nonce, realm_key_id, expires_at, answer, and session_id |
signature | string | The signature of signed_data. |
user.realm_get
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->realmGet();
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Get the public properties of the realm of which the user is a member. Requires either realm_key_id
or realm_id
.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | ? | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
realm_id | ? | string | The unique identifier for the realm to handle (this is not the same as the realm_key_id ). |
Return
Parameter | Type | Description |
---|---|---|
realm_id | string | An identifier unique to the realm. There is only one of these per realm. |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
display_name | string | Human-readable name describing this user |
open_enrollment | string | Whether or not the realm supports open enrollment |
user.rotate_key
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
// There is no PHP SDK available for this method.
// Please see our API Raw Call documentation instead.
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Sends a push notification to the registered presence, using the session_id
for verification.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
nonce | true | string | Cryptographic nonce for the request |
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
user_id | true | string | The unique ID of a user. |
user_key_id | true | string | A unique identifier mapped to a user’s current public key. |
pub_key | true | string | The user’s new public RSA key. |
Return
Parameter | Type | Description |
---|---|---|
username | string | The username of the current user. |
user_id | string | An identifier unique to the user. There is only one of these per user. |
user_key_id | string | The unique ID associated with each user_secret key |
user_secret_key | string | New secret key for user |
secret_enrollment_url | string | A tozauth URL containing the challenge, user_temp_key, and realm information necessary to complete registration |
secret_enrollment_qr_url | string | A link to a QR code containing a secret_enrollment_url |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
crypto_suite | string | The crypto suite used in the realm. |
display_name | string | Human-readable name describing this key |
user.user_add
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->userAdd();
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
Attempts to add a user without the realm’s signature. Used in open enrollment systems. If deferred, requires user.user_add_complete to be called later
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
defer | true | string | A string ‘true’ or 'false’ representing whether or not to defer enrollment. If 'true’, user.user_add_complete will need to be called to complete enrollment. |
extra_fields | encoded map | All the additional fields like username, email, birthdate, favorite color, etc. | |
remote_lat | string | Geographic latitude of device. Will be used as an additional security factor. | |
remote_long | string | Geographic longitude of device. Will be used as an additional security factor. | |
device_id | string | An identifier unique to each device (mobile phone, etc) | |
notification_id | string | Notification identifier of device for push messaging | |
device_description | string | Description of device | |
device_type | string | The mobile device OS. 1 represents iOS, 2 represents android | |
pub_key | string | The user’s public RSA key |
Return
Parameter | Type | Description |
---|---|---|
username | string | The username of the current user. |
user_id | string | An identifier unique to the user. There is only one of these per user. |
user_key_id | string | The unique ID associated with each user_secret key |
user_secret | string | The user’s secret key as stored on the Tozny API servers |
secret_enrollment_url | string | A tozauth:// URL containing the challenge, user’s temporary key, and realm information necessary to complete registration |
secret_enrollment_qr_url | string | A link to a QR code image containing a secret enrollment URL. |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
crypto_suite | string | The crypto suite used in the realm. |
display_name | string | Human-readable name describing this user |
user.user_add_complete
# There is no shell SDK available for this method.
# Please see our API Raw Call documentation instead.
// There is no Java SDK available for this method.
// Please see our API Raw Call documentation instead.
<?php
$api = new Tozny_Remote_User_API("YOUR-REALM-KEY-ID", "https://api.tozny.com");
$response = $api->userAddComplete('user_temp_key...');
# There is no Ruby SDK available for this method.
# Please see our API Raw Call documentation instead.
The second part of a deferred enroll or device add. Uses up the temp key granted to the user, replacing it with a permanent public key.
Arguments
Parameter | Required | Type | Description |
---|---|---|---|
realm_key_id | true | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
user_temp_key | true | string | The temp_key provided by a deferred enroll |
remote_lat | string | Geographic latitude of device. Will be used as an additional security factor. | |
remote_long | string | Geographic longitude of device. Will be used as an additional security factor. | |
device_id | string | An identifier unique to each device (mobile phone, etc) | |
notification_id | string | Notification identifier of device for push messaging | |
device_description | string | Description of device | |
device_type | string | The mobile device OS. 1 represents iOS, 2 represents android | |
pub_key | string | The user’s public RSA key |
Return
Parameter | Type | Description |
---|---|---|
meta | object | The realm-specific custom information on the user |
user_id | string | An identifier unique to the user. There is only one of these per user. |
user_key_id | string | The unique ID associated with each user_secret key |
user_secret | string | The user_secret stored on the tozny API servers |
realm_key_id | string | The unique identifier for a Realm’s key (There can be multiple of these per Realm). |
realm_id | string | An identifier unique to the realm. There is only one of these per realm. |
logo_url | string | Logo in the app for users |
info_url | string | URL in the app for users |
crypto_suite | string | The crypto suite used in the realm. |
display_name | string | Human-readable name describing this user |