Integrating with ZenKey is Easy

Whether you need to register first or are ready to access documentation right away, you’ll find everything you need here to quickly integrate ZenKey and enhance your customer experiences.

Here’s how to get started:
register
Register your Company
Register your company, configure your services, and obtain your client credentials.
sdk
Get the SDK
Download the SDKs and sample code for your platform (Android, iOS, and Web).
integration
Integrate your App
Start creating your ZenKey solution (Android, iOS, and Web)

trust
Need additional help to prevent fraud?
Add Trust Services to your ZenKey solution.
trust
Need additional help to prevent fraud?
Add Trust Services to your ZenKey solution.

MODRNA-based Discovery Flow

This discovery process for ZenKey was built using OpenID Connect MODRNA (Mobile Operator Discovery, Registration & AutheNticAtion) extensions. More information on MODRNA can be found here.

In this model, which will be supported for Service Providers that are interested in following the reference standards, the Service Provider makes two distinct requests. The first is for discovery, and the second is to the identified carrier for the authorization code.

The following is a high-level sequence diagram illustrating this flow:

How It Works

Under this model there are two discovery endpoints. The first is a user experience endpoint and is meant to be used by a browser client (or native client that can open a browser tab). The second endpoint is an API endpoint that returns the correct carriers OIDC configuration.

Carrier Discovery UI

https://discoveryui.myzenkey.com/ui/discovery-ui

  • Redirecting to this endpoint navigates to the choose your carrier UI
    -Required url parameters include client_id and redirect_uri
    -Optional url parameters include state, sdk_version and prompt
  • When the user selects their carrier, they're redirected to their redirect_uri
    -The response has url parameters mccmnc, state and login_hint_token (for secondary devices)

OIDC Discovery Issuer

https://discoveryissuer.myzenkey.com/.well-known/openid_configuration

  • A GET request to this endpoint returns the OpenID configuration document
    -Required url parameters include client_id and mccmnc
    -Optional url parameters include sub, phone_number and ip
  • The response is JSON with OpenID configurations including issuer, authorization_endpoint, token_endpoint and user_endpoint

Request Auth Code from authorization_endpoint

  • Redirecting to this endpoint navigates to the carrier specific authorization_endpoint
    -The required url parameters include client_id, redirect_uri, response_type, scope and state
    -The response_type=code for ZenKey purposes
    -The optional url parameters include login_hint_token (for secondary devices)
  • When authorization request is received the user is redirected to their redirect_uri
    -Response has url params code state mccmnc correlation_id error error_description

📘

Optimized Discovery Flow

If you're interested in the Optimized Discovery Flow you can view documentation here.

Updated 9 months ago


MODRNA-based Discovery Flow


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.