ZenKey Portal User Guide

The ZenKey Developer Portal (“ZenKey Portal”) is a self-service online portal that developers representing third-party Service Providers can use to:

  • Apply for access to ZenKey services;
  • Execute trial and service agreements;
  • Configure ZenKey services;
  • Submit help tickets;
  • View analytics (not yet available); and
  • View invoices, set up and executing payments (not yet available).

To set up your ZenKey developer account, please follow the instructions below.

Note: Third-party app and website publishers which use ZenKey to help authenticate their end users are referred to as “Service Providers”.

1. Register for your Individual Account

  1. Register for your individual account here.
  2. Enter the requested information, including name, company, role, email address, and phone number.
  3. Create a strong password between 12-128 characters.
  4. Agree to the Portal Terms of Use and Portal Privacy Policy.

These are the steps to set up your individual account in the ZenKey Portal. You are agreeing to the ZenKey Portal Privacy Policy and ZenKey Portal Terms of Use as an individual. Following validation of your email address, you will be able to formally submit your company, that is you will be able to apply for access to the ZenKey services.

After submitting the requested information, check your email to complete the registration process. If you don’t see the confirmation email in your inbox, check your spam folder. If you still have no luck, you can click the Resend Email button on the current Portal screen. Still no luck? Contact support by sending an email to techsupport@myzenkey.com.

After you’ve successfully validated your email address, go back to the Sign In screen to sign in for the first time. Make sure to check the reCaptcha box to show that you are a human.

2. Getting Started with ZenKey

Welcome to the Getting Started experience. Here you can access the Support page to submit help tickets to ZenKey; you’ll always find the Support link on the left-side panel in the Portal.

Getting started requires two preliminary steps before you can create your own project and clients (see Section 6 for information about projects and clients). You’ll need to have your company approved for access to ZenKey, and you’ll need to accept the Limited Trial Agreement. We’ll walk you through these processes here.

3. Submit Your Company

From the Getting Started tab, click “Start Submission”. Enter the requested information about your company, and press “Submit Company”.

ZenKey is only for companies which authenticate their customers or users and would like to improve security around those user accounts. ZenKey reserves the right to determine, in its sole discretion, whether your company is approved. For example, if your company has a poor record of security or protecting data, your submission might be declined. ZenKey will typically determine whether to approve your submission within a few days.

If your company is not approved, but you believe you have a strategic interest worthy of a discussion, please reach out to ZenKey through the contact form in the ZenKey Portal.

While waiting for your company to be approved, you may have a look at the Limited Trial Agreement. You may view the agreement online, or you may download it, to help with your review. After your company is approved, you’ll be able to formally accept the terms of the agreement and move forward.

Meanwhile, you may also take the opportunity to review the tools and resources available at the ZenKey Developer Website. In addition to technical documentation, you’ll find demo websites and the developer playground, where you can use your own ZenKey app (downloaded from the appropriate app store), and you can walk through the ZenKey experiences.

4. Review and Accept the Limited Trial Agreement

Once your company has been approved by ZenKey, you must accept the Limited Trial Agreement. These are standard terms – make sure to note the restrictions. The intent of the Limited Trial Agreement is to give you and your company the ability to integrate and test ZenKey before you make the decision to agree to commercial terms and receive the right to launch your integrated services publicly.

You will also need to acknowledge that you have the authority to agree to the Limited Trial Agreement on behalf of your company.

Once you agree, you can move on to Project Setup.

What if my company was declined

Your company may not have been approved for a variety of reasons. If you believe there was an error, you may re-submit. You may also reach out to ZenKey by submitting a question through the Support form within the ZenKey Portal.

5. Invite Other Users

Once you set up your company account in the ZenKey Portal, you can invite other coworkers to join you. After receiving company approval, and before accepting the Limited Trial Agreement, you can immediately start inviting other users.

  1. On the left-side of the Portal screen, click the Users link.
  2. On the User Management page, provide the name and email address of the new user.
  3. ZenKey sends an invitation email to the invitee.
  4. The invitee uses the link in the email to register for ZenKey.
  5. The invitee must provide their Company Role and Phone Number and agree to the individual Portal terms of use and Portal privacy policy. The user cannot change the name or email in the invitation.
  6. After completing the registration process, including email verification, the invitee can sign-in and join you in your company’s Portal account. You receive an email notification when the invitee registers for an account.
  7. To view the current users associated with your company account, visit the User Management page.

6. Project Set-up

Once your company is approved, and your company has accepted the Limited Trial Agreement, you're ready to tackle your first project.

Click “Start My First Project” or “Configure a new Project,” depending on what screen you’re on.

Important information about the ZenKey Project/Client hierarchy

A ZenKey project represents your app. You may choose to set up one client or multiple clients as part of your project. Some developers prefer to have a different client for each platform (Android, iOS, web), and some developers may choose to use different clients for different versions of their app.

End users cannot tell if you used different ZenKey clients for your different app platforms or versions. They can consent once, and then use ZenKey across your clients/platforms/versions related to a single project.

Some of the items you will configure below, are set at the Project level and are shared across clients within that Project. This includes: app name, logo, your terms of service, and your privacy policy.

You should create different projects for different apps or websites that consumers experience as different apps, typically accessed by separate user accounts and credentials [^1]. For example, a Weather App and a Horoscopes App will be different projects and will be named differently, appear separately in the ZenKey Directory [^2], and end users will need to consent to each app/project in order to use ZenKey with that app.

Each ZenKey client will be assigned a unique Client ID and Client Secret.

ZenKey Project/Client Hierarchy

Figure 1: An example of some ways to set up your Project/Client hierarchy.

[^1]: Note: Use multiple ZenKey projects by allowing end users to have one account/credential across multiple existing apps. Use the Sector URL to identify the same user across apps and projects. End users must consent to each separate project. A future option will let you use clients to represent your apps within a common ZenKey Project. The Project Name and Logo you set up displays in all cases; for all end user transactions across the related clients. End users only need to consent once to one client in a Project. Afterwards, the consent applies to all the clients in the Project.

[^2]: Note: The ZenKey Directory is a list of Service Providers which support ZenKey, which end users can access within the ZenKey app. When your company is in a Trial, your app will not be listed in the directory. When your company has agreed to a commercial service agreement, and your integrated service has been deployed with ZenKey, then your app will be listed in the directory. Then, end users can discover your app by browsing the directory.

Follow these steps to configure your project:

The project name you enter is how your app or service will be referred to in the ZenKey app experience. Project Name also describes your app or service when shown in the ZenKey Directory.

Project Name and Logo are automatically applied to all clients within the Project.

Check how your uploaded logo appears in the preview to make sure you’re happy with it in the integrated ZenKey experience.

Be prepared to provide the following information:

  • Domain URL (must start with http:// or https://)

    • This is the URL associated with your app or service which has ZenKey integrated. End users which discover your service while browsing the ZenKey Directory within the ZenKey app can press on your logo and go to this page, which may be your sign-in page where the end users can initiate their ZenKey set-up with your app or website. Some users may simply want to visit this link to find out more about your app or service. Users within the ZenKey app can press on your logo and go to this page, which may be your sign-in page where the end users can initiate their ZenKey set-up with your app or website. Some users may simply want to visit this link to find out more about your app or service.
  • Sector URL

    • Use a Sector URL to enable multiple clients to keep a consistent sub identifier, so you can identify a single end user across clients. The Sector URL is set at the Project level and automatically applies to each client in the Project.
    • You can also use the Sector URL across Projects, so you can identify a single end user across multiple apps.
  • Privacy Policy Link

    • You must provide a link to your app’s or service’s privacy policy. ZenKey shows this link to end users before they consent to using ZenKey (and potentially sharing data) with your app or service.
    • The Privacy Policy must cover all clients in a Project.
  • Terms of Service Link

    • You must provide a link to your app or service’s terms of service. ZenKey shows this link to end users so that they may read your terms, before they consent to using ZenKey with your app or service.
    • The Terms of Service must cover all clients in a Project.
  • Notification URI

    • This is where you will receive notifications of completed server-initiated authentication transactions.

All of the Project Links in this section are automatically applied to all clients within the Project.

The Advanced Links section can be used to help ZenKey users discover and open your app from within the ZenKey Directory. Be prepared to provide the following (all are optional):

  • iOS App Store URI
    • Provide the marketplace URL that allows users to download and install your app from the Apple App Store (e.g. http://itunes.apple.com/{Country_Code_Here}/app/{Your_Apple_ID_Here)&mt=8).
  • iOS App Launch URI
    • Enter either a URL Scheme (e.g. myApp:articleDetail?id=234) or Universal Link (e.g. https://www.myapp.com/article?234) that ZenKey can use to launch your app, if it is already installed on the user's primary device. If the system is not able to handle this URI, the user will either be directed to your Domain URL or to the iOS App Store URI, if provided.
  • Google Play Store URI
    • This allows ZenKey users to launch your Android app from within the ZenKey app.
  • Android Package Name
    • You may provide the unique identifier for your app from the Google Play Store and in the Android OS. This allows ZenKey users to open your app from the Account Details page, or install it from the ZenKey Directory, if they do not have it installed yet (e.g. com.example.myapp).
  • Android App Launch URI
    • Allows ZenKey users to launch your Android app from within ZenKey.

All of the Project Links in this section are automatically applied to all clients within the Project.

D. Data Attributes

Here you can find a list of data attributes available to be requested through ZenKey. Select which attributes are required or helpful to your app experience. When end users link their ZenKey app to your app or service for the first time, they will be presented with a consent screen and will have the opportunity to decline to consent to any attribute that you are requesting.

When the end users provide consent, that consent is provided to their wireless carriers, which will then provide the requested attributes to you, the Service Provider, when appropriate during the course of operating the ZenKey services. (see integration guides for the flows which allow data to be requested and shared)

The set of data attributes shown in this step, may change from time to time as more attributes become available. These attributes may be categorized and may have different cost implications – make sure to read the on-screen information and refer to your commercial agreement (if you have one) for those details.

TIP: You must request the desired attributes here in the Portal, in order to request them from a particular end user. If you do not set up a Project to include a request for end users to share their email addresses, then you will not be able to request it during your operation of ZenKey.

E. Trust Services

ZenKey offers certain Trust Services which can help you fight fraud. Refer to the Trust Services API Guide at the ZenKey Developer Website.

F. Security Contact

If ZenKey observes suspicious activity related to your app or service, we may reach out to inform you. Please provide contact information for an individual or team who should be contacted. This is typically a technical or operations-related function.

G. Review

Use the Review step to inspect the information that you enter. Click into any section to edit the values in the section. When done, press Submit. You can always review or modify the information in the future.

You now have a ZenKey Project with common information for all project clients. In the next steps, you create your first client and associate the client with the Project.

H. Client Descriptor

To make it easier to identify your clients, provide a short, descriptive name. Only you can view client names in the Portal. End users or carriers can not see the names of your clients.

I. Redirect URI

After using ZenKey to authenticate with your app, ZenKey uses your Redirect URI to redirect the user back to your app. Your real-time request must match one of the Redirect URIs in the ZenKey Portal.

The Redirect URI field in the ZenKey Portal pre-populates with a recommended value. The value starts with your Client ID. If you change the value and later want to re-use the recommended value, click the button.

The ZenKey mobile SDK assumes that you include a Redirect URI. If you change the URI, you must create a custom universal link for your mobile apps.

You can keep the recommended Redirect URI and add additional ones.

You may add multiple Redirect URIs:

  • To use different Redirect URIs in different environments, like development and production.
  • To use different Redirect URIs on different platforms that share the same Client ID.
  • To receive callbacks at different URLs by authorization type.

For more information about setting up Redirect URIs, see the Integration Guides

J. Final Step: Getting your Client Secret

ZenKey automatically generates a Client ID and Client Secret and displays them on the “Client Secret” screen. It is your responsibility to secure your Client Secret. Your Client ID is always available when you view your Projects and clients in the Portal page.

Click to acknowledge the above statements. To complete the process, click Finish.

L. What’s Next

You’re not ready to test the services just yet. The wireless carriers must provision your client. Currently, the provisioning step may take a few days, but will be faster in the future.

You can view the provisioning status of each client (at each ZenKey carrier) from within the Portal. (see the next section)

7. Projects Overview

After setting up your first Project and client, logging into the ZenKey Portal displays the Projects Overview page.

On the Projects Overview page, you can:

  • View your existing projects.
  • View the configuration settings and clients for a project.
  • Create a new client and add it to a project.
  • View the carrier provisioning status of each client.
  • View more details about a client, including Redirect URIs and carrier provisioning status. Client provisioning status is ‘Submitted’ until all carriers provision the client. Afterwards, the status becomes ‘Active’, setting the Project status to ’Active’.

8. Help and Support

As soon as you have completed registration of your individual account in the ZenKey Portal, you have access to the Support link on the left side of the screen. If you have any type of question or help request, you can contact ZenKey here.

Select an Inquiry Type, add a Subject, and describe your question or issue. You may attach a file, so you can provide screen shots or other helpful supporting materials.

For technical issues, please provide as many relevant details as you can, including for example:

  • Steps to reproduce
  • Debug logs or error printouts
  • Warnings or error messages observed
  • ZenKey SDK version number(s) involved
  • Carrier(s) involved
  • ZenKey mobile app version number(s) involved
  • Device type(s) and model(s) involved
  • Device software platform(s) and version number(s) involved
  • All client IDs involved.

After you submit your request, you will receive an automated confirmation email with your ticket number, and a representative will be in contact with you.

9. View Operational Analytics

Coming Soon

10. Billing Console

Coming Soon

11. Other Resources

Information Resources

The ZenKey Developer Website is a hub where you may familiarize yourself with educational multimedia, written documentation, visual diagrams, SDK source code, release notes, and other helpful content such as the:

For illustrative purposes, ZenKey also encourages you to visit with the ZenKey Demo website and interact with the website just as a consumer would by:

  • Selecting the “Sign in with ZenKey” button to view the carrier Discovery-UI (details below);
  • Simulating connecting a browser;
  • Downloading and setting up a personal ZenKey app; and
  • Testing various use cases.
Technical Resources

Technical resources and code related to the ZenKey SDKs and Web integrations are also available on a GitHub repository, which comprises three SDKs:

  • ZenKey iOS SDK
  • ZenKey Android SDK
  • ZenKey Web SDK

The assets above contain text files that explain the ZenKey integration for every available mobile platform, and chronicle the notable changes affixed to each major SDK version. More importantly, you may explore code, files, images, and installation instructions for various tools.

Visit the ZenKey Developer Playground to:

  • Observe the API calls available for both Identity Services workflows and Trust Services workflows.
  • Understand how ZenKey formats data that is returned.
  • Learn best practices for troubleshooting errors.
  • View endpoints necessary for authorization of an end user.

To navigate the “ZenKey Developer Playground”, access its User Guide for detailed instructions.

Revision History

Date Published Document Version ZenKey SDK Version Description
3.19.20 0.0.01 0.9.2 First published version.
4.30.20 0.0.02 Added Invitation experience and updated Project Setup
5.21.20 0.0.03 Removed Notification URI and Domain Proofing content
Last Update: Document Version 0.0.03, May 21, 2020

© 2020 ZenKey, LLC.