Developer Playground User Guide

Use the ZenKey developer playground to learn:

• How ZenKey works, including the ZenKey user authentication workflow steps and mobile device experience.
• The API calls and responses between the developer and ZenKey or the wireless carrier.

Prerequisites for using the ZenKey developer playground:

1. In a web browser on a laptop, desktop, or tablet open the developer playground (https://playground.myzenkey.com/playground).
2. Install and set up the ZenKey app for your wireless carrier on your mobile phone myzenkey.com/download.

🚧

Viewing Developer Playground on a Mobile Phone

Although the Developer Playground works on a Mobile Phone, it is currently optimized for a larger browser experience.

The ZenKey Developer Playground UI

• A sidebar on the left: contains settings, steps for identity services, steps for trust services, and the server-initiated flow to get auth tokens.
• A window on the right: displays the request submitted by the current step and the response you use to build the next step request.
• A reset button: reverts the UI fields to their default values and re-starts the workflow.
• Default values for fields and properties.

Sidebar Step Menus

• Settings: Lists the playground’s Client_Assertion or Client_Secret, Correlation ID, and redirect-URL. Most of these items are read-only.
• Identity Services: Lists the sequence of steps you must follow: submitting a request and retrieving the response to use in the next step.
• Trust Services: Lists additional options for simulating the Trust Services for fraud detection and prevention workflow.
• Server Initiated: Lists the server-initiated flow for getting auth tokens without code.

Workflows in the Playground

Perform the playground steps in the order they occur in the UI. Each step auto-populates the next step’s request based on the previous step’s response.

Identity Services Workflow

Step: 1. Discovery Issuer - Discover the user’s carrier.

• Request: Discover the user’s carrier. Parameters: - Client_id*
• Response: If the carrier is found, return the proper OIDC configuration. If not, return the redirect_uri to the discovery_ui endpoint to identify the carrier.

Step: 2. Discovery UI.

• Request: Applied when the carrier is not found in step 1. Parameters: Client_id, Redirect_uri.
• Response: Displays a “Connect browser to your ZenKey” page to scan a QR code or visual code, or enter a manual code to add the browser as a trusted device, and redirects the browser to the playground (acting as a web app). The response includes the MCCMNC.

Step: 3: Discovery Issuer.

• Request: Discover the user’s carrier and return the OIDC endpoints. Parameters: client_id, mccmnc (returned from Step 2).
• Response: If the carrier is found, return the proper OIDC configuration. If not, return the redirect uri to the discovery_ui endpoint.

Step: 4: Authorize

• Request: Request authorization. Parameters: client_id, Login_hint_token, Context, Nonce, Redirect_uri, Response_type, Scope*, State.
• Response: Returns a code used in the request body of the next step, “Step 5: Token”.

Step: 5: Token

• Request: Request token
• Response: Returns the authorize token

Step: 6: User Info

• Request and Response: Request is submitted to the carrier user info endpoint.

Trust Services Workflow

Step: User Trait

• Request and Reponse: Post request for sim_tenure indicator. You can specify the base URL, header, body, event types (such as Security, Device Change, Consent Revoked, Profile Change).

* = Required parameter