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.

(Coming soon) Managing Carrier Migration

📘

A future release of ZenKey will support account migration. Meanwhile, Service Providers can begin using the following instructions now as required.

ZenKey will support users that migrate to a new phone carrier. When a user migrates from one carrier to another, the user is assigned a unique identifier (the user’s “sub”) based on the new carrier. If the user opts to migrate their ZenKey to the new carrier, ZenKey provides a reference to any previous carrier sub for the user. You can replace any stored deprecated user subs with the new one.

A user can move their ZenKey within 180 days of porting their line.
After the user migrates ZenKey to their new carrier, their subsequent ZenKey logins for the next 180 days will contain the port_token.

How to detect and handle a user that migrated to a new mobile carrier

When a user that migrated to a new carrier uses ZenKey, the current/new carrier handles the migration process. The ZenKey SDKs, or the discovery-ui endpoint, manage the transition automatically. The response you receive from the carrier’s token_endpoint contains the current/new sub that identifies the user. The sub also contains an array of JWT port_tokens in the “aka” parameter of the id_token. These port tokens identify previous subs for the user.

A decoded port token contains data in the following format:

{typ=port_token+jwt,kid=xxx}
{
  "iss": "https://ZenKey.old_carrier.com",
  "sub": "mncmcc-75984731587234asdf",
  "iat": 1516239022
  "aud": client_id
}

To determine if a user is a new or returning user, complete the carrier token request on your secure server. Afterwards, perform the following steps:

  1. Search your user database for the user’s current sub. You should always reference the user by their sub and not the user's phone, email, or other property. Those properties could change, or the user may opt to not share them with you.
  2. If you find a user in your database with the matching sub, proceed with that recognized user and skip the remaining steps below. Otherwise this may be a user that migrated to a new carrier, or a new user.
  3. Decode any port_token JWTs. If there are no port tokens, this is a new user. Prompt the user to register or link an existing account as appropriate for your service.
  4. Verify that each port_token issuer (iss) URL is a trusted carrier. The following is a list of valid iss URLs:
    • *.att.com
    • *.verizon.com
    • *.t-mobile.com
    • *.myzenkey.com
    • *.xcijv.com
  5. Use the port_token issuer (iss) URL to extract the OpenID configuration of the old carrier and get their JWKs. Use the key ID (KID) in the port_token to identify the JWK key to use to verify the token’s signature.
  6. Search your database for user accounts linked to the subs in verified port tokens. If you find a user with any of the old subs, update the references in the database to the new sub from the new carrier.
  7. If you cannot find a matching user, you can treat the user as a new user for your service. For more information, see the Notes section.

📘

Notes

  • Always provide all new users with the option to link to an existing account for your service, even if the existing account in your database is already linked to a (possibly old) user.
  • A user may choose not to migrate their ZenKey or may not use your app within 180 days of migration. Therefore, a new or unrecognized user might still be a returning user of your app.
  • If a user migrated carriers more than 180 days ago, the new carrier may no longer provide a port_token.
  • There are other scenarios where an existing user appears to be a new ZenKey user. For example, if a user is locked out of their ZenKey and unable to recover the account, the user may choose to create a new ZenKey.

Updated about a month ago


(Coming soon) Managing Carrier Migration


Suggested Edits are limited on API Reference Pages

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