NAV
php ruby java shell objective-c swift android

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:

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:

Often, when integrating Tozny with an existing user database that uses passwords, there will be several additional steps when enrolling a user:

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
  1. User enters their email into your application, which is then sent to your back-end for validation
  2. 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 a toznyo 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
  1. Use the Tozny SDK to provide a link Result of either an email verification or an error (e.g. link expired, etc.)
  2. If the email verification was successful, you can use the SDK to perform an enrollmentChallengeExchange with the verification result to get a Tozny EnrollmentChallenge
  3. 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
  1. Use the Tozny mobile-sdk to authenticateUser which will supply a signed payload and signature.
  2. 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:

  1. Log in to the Tozny Web Console.

  2. Activate the pop-up menu in the upper right and select “Settings”. Realm Settings

  3. Click the “Edit” button in the upper right to edit your realm settings. Edit Realm Settings

  4. Scroll down near the button and click “Open Enrollment” so that the toggle button show “YES”. Enable Open Enrollment

  5. 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:

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:

<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>
<div id=”tozny-login”></div>
$(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.

// 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
  1. User enters their email into your application, which is then sent to your back-end for validation
  2. 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
// 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:

Getting your Tozny API Key

  1. Login to your Tozny account at https://admin.tozny.com.
  2. Navigate to the “Keys” area of your realm.

Keys administration 3. Click on the name of the key you want to use, or create a new one

Key identification 4. Your key information will appear midway down the page. Your secret can be retrieved by clicking on the ‘view’ link.

Secret key

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:

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
# 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
# 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
# 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