Trust Services API Guide for Service Providers

This document introduces Service Providers to the Trust Services API, which offers additional fraud prevention services to ZenKey mobile security for protecting users and application resources.

ZenKey is an undertaking of the Mobile Authentication Taskforce, which is a joint venture of the four major US wireless carriers. The platform leverages encryption technologies in a user's mobile phone and mobile network, and packages multiple factors of authentication into a streamlined experience for app and website providers. It takes advantage of the unique capabilities and insights of the wireless carriers, and applies an easy and secure way to register, login, and perform other types of authorizations within apps and services. The result for Service Providers is a better user experience and a more secure link to users. ZenKey makes integration easy by following the OpenID Connect (OIDC) authentication protocol.

1.0 Background

Account take over fraud is the leading SIM/wireless fraud attack vector impacting the Financial Services industry. Often this is conducted by a bad actor who swaps a mobile device's SIM card. He or she then calls the mobile carrier's customer service representative and dupes them into believing the SIM was damaged or lost and providing the necessary recovery information to restore service. This might entail moving the victim's phone number from SIM 1 and associating it with the fraudster's SIM 2. The thief then attempts to log into the victim's bank account using the stolen username and password, and faces the bank's challenge for 2nd factor authentication. On success, the bank sends an SMS OTP to the new SIM card. The fraudster enters the 2FA challenge response and successfully logs into the victim's bank account.

The ZenKey platform provides SIM swap protection that presents a stark contrast to the typical fraud outcome. However, for mobile users to benefit from this protection, they must have ZenKey installed on their device and the ZenKey app linked to the Service Provider's app or website.

Whenever a SIM swap occurs on a ZenKey user's mobile device, a recovery flow is triggered, and the user must respond appropriately to regain access to the account. This can be easily performed by legitimate ZenKey users but not as easily by the fraudster who would have to download and install ZenKey, and successfully provide at least 2 out of the following 4 alternate factors of authentication as part of a built-in recovery flow:

  • PIN/biometric
  • Recovery code (setup during ZenKey sign-up)
  • Trusted device (registered during ZenKey sign-up)
  • Carrier username/password

Trust Services was added to ZenKey at the request of several financial institutions who wanted additional API functionality that would enable them to be more proactive in detecting and thwarting fraud by bad actors who have taken control of bank accounts by way of a SIM swap. Trust Services provides a suite of fraud prevention services that sit on top of the ZenKey security platform.

1.1 Overview of Trust Services Fraud Prevention

Trust Services is a collection of different types of APIs and event alerts made available to Service Providers. These will be useful in situations when a Service Provider suspects fraud with their user accounts. Initially, Trust Services will offer these two fraud prevention features (as more are added this document will be updated):

  1. The SIM Tenure Indicator option allows the Service Provider to query carriers via an API call and learn whether the SIM card for a given user has changed within the past 24 hours.
  2. A subscription-based, automated "device change event" alert option provides an immediate message to the Service Provider that is triggered by qualifying mobile user activity.

REMEMBER: The only preconditions for your users to benefit from these added Trust Services is to have ZenKey installed on their mobile device and linked to your app. Users who do not consent to using ZenKey will not be protected!

1.1.1 Different Workflow Options

The Service Provider has the option to:

  • Query a user's SIM Tenure indicator, or
  • Automatically receive alerts about a triggered event indicating that the user's mobile device has changed.

The Service Provider can select the option that matches its fraud prevention objectives, or both options if preferred. The following diagram illustrates the service flows for these two options (blue for API call, green for event alert).

Trust Services 1.0 Service Flows

1.1.2 SIM Tenure Option

By implementing the SIM Tenure option, the Service Provider can at any time perform a SIM check ahead of attempted banking transactions for their selected users.

For example:

  1. A selected user attempts a mobile banking transaction.
  2. Based on the user's carrier ID (MCCMNC), the bank submits a request to the API to verify the user’s carrier information. For example, the following request is sent to the discoveryissuer endpoint.
  1. The response includes the endpoint to the user's carrier and the associated openid configuration. For example,
{"issuer":"", "authorization_endpoint":"", "token_endpoint":"", "jwks_uri":"", "response_types_supported":["code","token"], "subject_types_supported":["public"], "id_token_signing_alg_values_supported":["RS256"]}
  1. The bank submits an API query to the carrier for the sub-ID for the user. (The Subject Identifier, or subis locally unique and a never-reassigned identifier within the Issuer for the end user.)

POST /v1/usertrait  HTTP/1.1
Content-type: application/json
Cache-control: no-cache
x-authorization: <proof-of-possession>

  1. The carrier checks the user's SIM tenure indicator.
  2. For the SIM tenure indicator during the last 24 hours, the carrier sends a response to the bank with true, false, or error.

HTTP/1.1 200 OK
Content-type: application/json
 "sim_tenure": "true"
  1. The bank inputs the sim_tenure API response into its fraud prevention system and schedules whatever action it deems appropriate, such as to accept the transaction, reject it, or put it on hold for further checks.

The following UML (Unified Modeling Language) diagram and script shows the workflow with the associated main actors, roles, actions, artifacts and classes.

SIM Tenure Swimlane Diagram

@startuml sim_tenure_24participant spbox "jv"
participant score as "fraud score"
participant di as "discovery"
participant auditlogs
end boxbox "mno"participant source
participant CCID_IDP
participant usertraitnote over sp,usertrait
   SP has previously authenticated a user
   and tracked their Sub id
end notesp->sp: identify a usersp->di: call discover
di->sp: latest carrier configsp->sp: generate request
sp->sp: sign requestsp->usertrait: query
usertrait ->CCID_IDP: verify sp authentication
usertrait-> CCID_IDP: verify user has consented SP
usertrait-> source: fetch tenure
usertrait-> usertrait: format response
usertrait-> sp: sim_tenure_24:true|falseusertrait -> auditlogs: usertrait log@enduml

1.1.3 Device Change Event Alert Option

An alternative to the Sim Tenure option is the device_change event alert, which can be sent automatically to the bank as notification of a potential SIM event for any of their ZenKey users. This differs from the SIM tenure option in that:

  • The bank does not have to explicitly submit an API call for the SIM tenure.
  • The automatic device_change event alerts the bank that some change has occurred with the device or SIM associated with the given MDN.

For example:

  1. The carrier system detects the SIM swap for the user's phone.

  2. The carrier relays a SIM swap alert to the bank by a set token to the bank's registered event endpoint.

    The following illustrates an event posted by the carrier to the Service Provider's configured event host when the device_change event is triggered.

POST <sp_conifigured> HTTP/1.1
Host: <sp_configured_event_host>
Content-type: application/json
Cache-control: no-cache

“set”:” eyJ0eXAiOiJTRVQrSldUIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJ4In0.eyJpc3MiOiJhY2NvdW50LnQtbW9iaWxlLmNvbSIsImlhdCI6MTUwNDYzNTYsImp0aSI6IjMyNGdzaW81NmtsMzI0bW5kZnNsamszMjUiLCJhdWQiOiJjY2lkLW9hdXRocGxheWdyb3VuZDAiLCJzdWIiOiIzMTAyMTMtVTU0NjY0NTM0NS0zNDI1My00NjM0IiwiZXZlbnRzIjpbInNlY3VyaXR5X2V2ZW50Il19.QqPUF5JgiW94eZvGxN4is_-f9PJN9TZpMsQW6ER6giGxWYBmClgCbvQC2FRu534H-5_xhdh1M71QzdV4y7O2amPLF2vVOEhtT3_8wFvsgr3H-wgQ1ScFWWg5wV18HWT-PvweTHOlHG0NLa2Ou0mFDIm6LKsBJJY5E4npPysIVdVFAy_SCUwOPUrYl-7TqipyDpxHilBxKUPMdpZsJzEwLXy21PgQnJwuIm14HpritVTJjm2gW7WwxuJ1kUINWYfy6wkp2umwbHWhYwstYPR78CeDkOKq4mnbwLvlMfy5cHPJ80xpSKXSURDzQ3G9c8Q8WBeOZSQvRXnnCfE_utFaNw

The SP should reply with a “200 OK” to confirm receipt. If the carrier does not get a “200 OK”, the carrier will retry up to 3 times at 1-minute spacing before recording an error. The carrier caches the combination of (pairwise sub, SP, event, time).

NOTE: The pairwise sub ID for this event should begin with mccmnc-.

If a duplicate event is generated within 60 minutes of a previous (pairwise sub, SP, event), the carrier drops and does not send the duplicate event.

The following is a sample decoded set token.


  1. The bank can input this alert into its fraud prevention system and schedule an appropriate action.

The following diagram illustrates the related architecture.

Alert Flow

This option requires:

  • A subscription to the service.
  • SP Event Alert endpoint.
  • Request for "event" scope.

If you subscribe to this service, you will be notified whenever a device_change event has occurred for a connected and consented end user. This is useful to be prepared for subsequent interactions with the identified user. Possible scenarios for the carrier triggering this event include:

  • User has moved their SIM to a new device.
  • User has factory reset their device.
  • User has changed their SIM card.

Each carrier defines a usertraits endpoint in their OpenID configuration. To access this endpoint, you must make a request to the ZenKey Joint Venture via the Service Provider Portal.

By setting the SP Client ID usertraits_enabled parameter, the SP can query for a singular carrier attribute, signal, or indicator. Currently, the only supported attribute is sim_tenure.

NOTE: A user's sim_tenure scope is set to true when an existing SIM is associated with the user's phone number for less than 24 hours.

Each carrier may track a specific event (similar todevice_change) to inform Service Providers that the user’s primary device has changed. For example:

  • User has moved their SIM to a new device (e.g., associating from an IMSI to an IMEI device).

  • User has changed the device's SIM card (e.g., associating a phone number to an IMSI).

    • The carrier may track the association of a phone line to an IMSI. The objective is to track SIM swaps, not phone number changes.

NOTE: A user leaving their SIM in place but asking for a new phone number will be identified as a profile_change and not a device_change, which is a different event alert (not currently included in this offering).

2.0 Getting Started

There are several prerequisites you should complete before implementing the specific MID-Premium service option with ZenKey and your applications:

  • Register with the Service Provider Portal.

  • Ensure your users and MDNs have installed the ZenKey app on their devices.

  • Ensure your app or website has been linked and working with ZenKey.

  • If you will be using the automatic alert option, subscribe to the automatic alert service by visiting the Service Provider Portal.

  • Configure one or more of the following:

    • Events scope access:

    • call_verification_enabled

    • Fraud_score_enabled

  • Configure enum_enabled.

  • Configure contact numbers, such as:

    • 1-800-callme

    • +1-555-666-7777

3.0 Implementation

Once you have set up the prerequisites noted in the "Getting Started" section of this document, configure and test the MID-Premium option you have selected.

3.1 SIM Tenure Option

Configure the Option

For the SIM Tenure option, configure the following:

  • User behavior actions to be monitored, such as attempted bank transactions, and/or users/MDNs to be checked for sim_tenure indicator.

  • Process for querying the user's carrier.

  • Process for checking sim_tenure indicator.

  • Process for inputting the sim_tenure indicator into your existing fraud prevention system.

  • User remediation - actions to be implemented for users whose sim_tenure is false.

Test the Option

Use the simulator tool and environment of your choice. Follow these steps to test your implementation:

  1. Swap a mobile phone's SIM card.
  2. Use the phone to connect to your application.
  3. Submit an API query to the carrier for the phone for it's sim_tenure indicator.
  4. Review the response.
  5. Check that the sim_tenure indicator for your phone was input into your test fraud protection system and and remediation actions have been set.

3.2 Device Change Event Alert Option

NOTE: Ensure that you have subscribed to the automatic alert service.

Configure the Option

For the Device Change Event Alert option, configure the following:

  • Process for inputting the device_change event into your existing fraud prevention system.
  • User remediation - Associate actions to be performed when a device_change event is received by your fraud detection system.

Test the Option

Use the simulator tool and environment of your choice. Follow these steps to test your implementation:

  1. Add or switch your SIM card to a new device.
  2. Use the phone to connect to your application.
  3. Check that an alert is received from the carrier that identifies the device_change event.
  4. Check that the alert is inserted into your test fraud protection system and and remediation actions have been set.
  • XCI-ProviderIntegration-Web
  • XCI-ProviderSDK-Android
  • XCI-ProviderSDK-iOS


For technical questions, contact support.

© 2019 ZenKey, LLC

Revision History

Date Version Description
12.17.2019 1.7 Added ZenKey, LLC copyright.
12.04.2019 1.6 Deleted License Notice.

Last Update: Document Version 1.1 - December 17, 2019