How to Integrate an Access Control System with Schlage Mobile Credentials Solution

Credential Lifecycle Management Guide

Last modified: 12.19.2024

The purpose of this guide is to walk an Access Control System provider's software development team through the steps necessary to integrate the Schlage NFC-based Mobile Credential solutions with their Access Control System product. With the information covered in this guide, a software team is prepared to complete the integration so that they can begin to include Schlage Mobile Credentials for iOS and Android as a feature for their customer deployments.

This guide is relevant for Mobile Credential implementations across Employee Badge, Student ID and Multifamily verticals.

Schlage Mobile Credentials allow credential bearers - or patrons - to store an NFC-based credential in the digital wallet of their iOS or Android device (or paired Watch device) and use that credential in place of physical credentials. This guide covers the work necessary to complete direct integration of an Access Control System (ACS) with the Schlage technologies necessary to achieve full Credential Lifecycle Management between ACS and Allegion systems. After this work is done, mobile developers will follow the details covered in the How-To Guide for Building a Schlage NFC Mobile Credentials App for iOS or the How-To Guide for Building a Schlage NFC Mobile Credentials App for Google Wallet to provide their customers with an app used for user authorization and credential provisioning.

Target Audience for this Guide

This guide is intended to be read and used by Access Control System solution providers, and specifically the software engineering resources responsible for building integrations to 3rd-party solution providers such as Schlage, including cloud developers and project managers. It will also be useful for technical resources responsible for provisioning credential management systems and technical administrators responsible for managing credentials.

Mobile Credentials High-Level Architecture

Schlage Mobile Credentials give patrons the ability to use an NFC-based credential - known as a pass - stored in their phone's/watch's Wallet - to gain access to secured spaces managed by an Access Control System (ACS). This guide will not focus on the app development work, but instead will focus narrowly on the work to be done to achieve the integration represented by the lines between the Allegion Cloud and the Access Control System in the diagram below:

As the diagram above illustrates, the Schlage NFC Mobile Credentials solution relies on cloud-based integration between an Access Control System and the Allegion Cloud in order to facilitate Credential Lifecycle Management (CLM) activities, alongside the Schlage Mobile Access SDK to support provisioning credentials into the digital wallet. Users will use their mobile device to log into their organization (using credentials managed by their organization's Identity Management System) and request a mobile credential be generated for their use. Once generated, the credential will be provisioned into the digital wallet and be available for use directly from the NFC-enabled wallet app.

Note that communication between Allegion and the digital wallet is brokered through the digital wallet providers (Apple/Google). This means that lifecycle interactions with the pass are managed through APIs provided by Schlage, which in turn handles communication through digital providers and to the wallet. The Schlage APIs expose interfaces to allow Access Control providers to manage the credential lifecycle.

Lifecycle of a Mobile Credential

All credentials, whether physical or digital, exist within a lifecycle. The Credential Lifecycle is the well-defined and finite timeframe and set of activities by which a credential can operate. Credential Lifecycle Management (CLM) is the set of policies and procedures that define and enforce the creation, activation, assignment, updates, suspension, resumption, deactivation and revocation/destruction of a credential within an organization or system.

Both physical and mobile credentials operate according to a defined CLM program. The processes for managing mobile credentials are similar to those used for physical credentials, but mobile credentials bring unique benefits - and challenges - that require special consideration in order to ensure they meet necessary security, compliance and governance policies. Mobile credentials - by nature of the number of systems involved in their daily operation - exist in a more dynamic environment than physical credentials. The state of a mobile credential can be impacted by different systems and that state must be maintained across those systems. Because digital credentials live in the wallet of connected mobile phones and watches, opportunities to take advantage of the always-connected features of those devices allow for more proactive credential management than is available for non-connected physical credentials such as keycards or fobs.

For instance, in situations where a user loses their device, credentials can be immediately suspended by the user themselves from a secondary device. If the device is safely found then the user can initiate resumption of the use of their pass immediately. Likewise, if a user's pass is suspected of being compromised by an unauthorized person, Access Control system managers needs a way to suspend or terminate passes remotely.

These interactions highlight the fact that changes to the status of a user's credential may be initiated from different places and must be kept in sync across different systems. During the course of an NFC credentials lifetime, Allegion will need to be able to call an ACS to provide status updates such as credential activation, suspension, resumed use, and deletion. Credential Lifecycle Management processes must account for these interactions in order to ensure they result in expected behavior across all systems. This is why CLM is an important component of any mobile credential strategy. This guide focuses on building integrations to support CLM processes and provides best practice guidance on how to build a Credential Lifecycle Management program using Allegion APIs that achieve required synchronization across systems.

Mobile Credential Lifecycle Management Operations

There are 5 basic operations involved in the synchronization of a credential across Allegion, Access Control System and Digital Wallet Provider:

These operations expose the necessary behavior to achieve full pass support in the Digital Wallet, and must be implemented and verified as implemented in order for the Access Control provider to begin offering Schlage mobile credentials as a feature of their access control solutions. The operations are used across multiple use cases, documented in the next section.

Also note that these operations include work done by a mobile app to support activities such as adding a pass to a wallet or updating a pass in the wallet. This guide focuses on the activities related to the cloud-to-cloud interactions between a PACS system and the Schlage cloud. Details on the app side of these operations is covered in the How-To Guide for Building a Schlage NFC Mobile Credentials App for iOS or the How-To Guide for Building a Schlage NFC Mobile Credentials App for Google Wallet.

Access Control Systems operate in different ways to support their goals, and so we do not provide one-size-fits-all requirements on pass lifecycle management implementation. Intead, this guide seeks to provide best practice guidance on what types of activities should take the pass into account, along use case scenarios that should be supported to ensure effective pass lifecycle management. Development teams can use this guidance and use cases to build their integration support. Once all use cases are implemented, Schlage will validate the implementation to confirm it is ready for a customer deployment. Use cases are documented below.

Mobile Credentials Implementation Use Cases

The following use cases should be supported for a PACS Mobile Credentials Integration project. These are use cases that the Digital Wallet Providers will validate as functional before granting production approval for use of their Digital Wallet:

The five operations detailed in the previous section can be used to complete all use cases.

Note that some of these use cases describe actions initiated from different systems; some are initated from the user on their device, and others initiated from the PACS system/customer. The Schlage Mobile Credentials APIs support processing pass management requests from both directions.

From here we'll cover getting a developer access to Schlage Mobile Credential PACS API and working through implementation.

Overview of the ACS Integration to Schlage Mobile Credentials Platform

Schlage Mobile Credential Lifecycle support is implemented using two APIs - one provided by Schlage and the other provided by the Access Control System provider/integrator:

The Schlage Mobile Credential PACS API

The Schlage Mobile Credential PACS API - this API is hosted in the Schlage Cloud and access to the API - along with detailed documentation - is made available through the Schlage Developer Portal. The purpose of this API is to support creation, management and brokered synchronization of credentials between ACS and Digital Wallets via Digital Wallet Providers.

Allegion maintains API Definitions for Employee Badge, Student ID and Resident Key (Multifamily) on the Developer Portal at the following locations:

• Employee Badge API Documentation

• Resident Key API Documentation

• Student ID API Documentation

At those respective URL locations you can find links to downloadable API definitions in OpenAPI (formerly Swagger) and WADL specifications which can be used to generate sample requests in web API development environments such as Postman.

Vertical-specific Endpoints

Allegion hosts a different set of endpoints for Student ID, Employee Badge and Multifamily credential integrations. Refer to the table below for the URL for each vertical:

QA Environment Endpoints

Production Environment Endpoints

The Credential Events API (Pattern)

The Credential Events API (Pattern) is hosted by the ACS (or other party with programmatic access to perform ACS updates on behalf of a customer) and is responsible for receiving credential lifecycle events sent by the Allegion Cloud and processing them against the ACS. This guide covers the design and specifications required for developing and exposing this API for use by Allegion to allow dispatch of events from Allegion to ACS. Creating this API requires the ACS Provider or Integrator to have the ability to expose two endpoints that Allegion will use to post (POST) credential lifecycle events to the ACS for processing.

Other requirements for implementation include:

• An Access Control System (ACS)

• The ability to generate and post (POST) structured JSON payloads to the Allegion API

This guide assumes the developers working to build the integration meet the following minimum experience requirements for completing such a task:

1. Developers have access to an Integrated Development Environment (IDE) and API testing tool such as Postman.

2. Developers have experience working with REST-based APIs to build software.
   
   

Getting Access to the Schlage Mobile Credentials PACS API

1. Create an Allegion Developer Account and Request a Mobile Credentials API Subscription

If you have not already done so, you'll need to create an account in the Allegion Developer Portal in order to gain access to the API and SDK documentation for Allegion Mobile Credentials products. You'll also need this account to obtain an API Subscription key, which is required to initialize and use the SDK within your app and communicate with the Mobile Credentials API.

1. Click here to reach the Allegion Developer Portal

   

2. Click the Sign In link in the top right corner of the landing page.
   
   
   
3. If you have an account, enter your account details and click Login to log in.

   

   If you don't have an account, click the Create Profile button to create an account. Enter required details to create an account and complete the email verification step to continue. You'll also need to complete profile details to proceed.

   
   
4. Once you have your profile, upon login you'll be directed to your Account Profile page. This is the area where you'll see API subscriptions that you've created in your account. If this is a new account or you've never created an API subscription then you'll see an empty list here that displays, "No results found":
   
   

   

   
   
   
5. To create an API subscription, you'll first need to request access to the Allegion Mobile Credentials NFC APIs. The Allegion Mobile Credentials API is called "Persona Manager". Allegion will grant PACS developers access to Subscriptions for a PQA environment as well as a Production environment. To make this request, click here to send in a ticket request to Allegion with the following details:
   
   

   Subject: New Allegion NFC Mobile Credentials API Access Request for [YOUR COMPANY NAME]

   Body:
   
   I am a developer with [YOUR COMPANY NAME] working to build integration to support Allegion NFC Mobile Credentials. I have created an Allegion Developer Portal account with the following email address:
   
   [EMAIL ADDRESS USED TO CREATE AN ALLEGION PORTAL DEVELOPER ACCOUNT]
   
   
   Please grant this account PQA and Production environment access to Allegion Persona Manager NFC Mobile Credentials APIs.
   

   
   Allegion will process this request within 24 hours. Once a response is received from Allegion with notification of API access grant, move on to the next step.
   
   

   ℹ️ Limit One API Subscription Key and one Mobile SDK Subscription Key per Company

   Allegion will only grant one API Subscription Key and one Mobile SDK Subscription per Company. If multiple developers on your team have an Allegion Developer Account, you'll want to choose one of those accounts to receive the subscription. Only one key is needed for development, regardless of the number of apps you plan to build.
   
   
   
6. Once a response from Allegion is received notifying you that developer account access to the Persona Manager APIs has been granted, log back into the Allegion Developer portal and click on the Products tab link. APIs to which your account has been granted access will be listed here:
   
   
   
   
   
   You should see the following APIs listed on the Products Page:
   
   
   • Persona Manager PACS - PQA - This is the Development and QA environment API which which developers should start their development work.
     
     
   • Persoana Manager PACS - Prod - This is the Prod environment API, used for PACS customer deployments.
     
     
   
   Clicking on either of these Products will lead to sub-product page listing 3 different, vertical-specific Allegion Mobile Credential APIs:
   
   
   
   
   • Employee Badge - This API is used to build integrations to support Corporate badge implementations.
     
     
   • Student ID - This API is used to build integrations to support Higher Education (non-K-12) badge implementations.
     
     
   • Resident Key - This API is used to build integrations to support Multifamily Resident badge implementations.
     
   
   
   Subscription keys can be used across verticals, but not across environments. For instance, a subscription key generated for use with the Persona Manager PACS - PQA environment will not authorize requests to the Persona Manager PACS - Prod environment.
   
   Clicking on any of these 3 products will take you to a page that allows you to exercise the APIs and provides access to an Open API Spec that can be downloaded and used to create reference API calls or scaffold requests in a tool like Postman or Visual Studio Code.
   
   
   
   
7. From here, you're ready to create a Subscription key. Navigate to the Products tab (if no longer on that page) and click on the Persona Manager PACS - PQA product.
   
   
   Click in the text box with tex, "Your new product subscription name" and enter a name for your PQA subscription key, then click the "Subscribe" button to create a subscription:
   
   
   
   Upon creating your subscription key, the screen will be redirected to the Profile page where API subscriptions are listed along with subscription keys. Each API subscription has a primary and a secondary subscription key:
   
   

   

   
   
   Your application can use either of these keys but should be consistent across the application (ideally only use one or the other per application). To reveal the subscription key in order to copy it and paste it into your IDE, click the "Reveal" button.
   
   Multiple subscriptions can be created if your company has a need to isolate and identify requests for environment-specific reasons such as multiple Development Environments.
   
   
   
   Subscription keys represent an environment from which requests are made to Allegion - they do not identify clients.

   Subscription keys grant your company access to execute requests against the Allegion Mobile Credentials API. Subscription keys ideally represent a unique environment from which requests to Allegion will be made for request tracing purposes - such as identifying an API call made to Allegion from a Development environment vs a QA or Regression Testing environment. Subscription keys are not intended to be used to identify/represent individual clients. Client IDs are used to represent individual clients of your application(s); a single Subscription key will/should be used with any number of Client IDs when making requests to Allegion. Integration IDs represent a unique identifier for your company across an Allegion environment and all clients and subscriptions in that environment. Client IDs and Integration IDs are covered in more detail later in this guide.
   
   

2. Create mTLS Certificates (keys)

Communication to Allegion cloud-based technology is secured through a trust relationship established using Mutual TLS or mTLS authentication. mTLS is an end-to-end security method for mutual authentication that ensures both parties are who they claim to be before data is shared. mTLS uses public/private certificate pairs - or key pairs - to establish identity between two parties. (The terms key and certificate are used interchangeably throughout this guide.)

One key pair is shared by Allegion and the other is shared by the partner communicating with Allegion. Each party will share their respective public keys with the other:

• Partner mTLS API Keys: Payloads generated by the partner will be signed using the partner private key and sent to Allegion via POST request. Upon receipt of the message, Allegion will use the partner's public key (sent to Alegion ahead of time) to verify the partner signed the message using the partner's private key.

• Allegion mTLS API Keys: Payloads generated by Allegion will be signed using Allegion's private key and sent to the partner via POST request. Upon receipt of the message, the partner will use Allegion's public key (sent to the partner ahead of time) to verify Allegion signed the message using Allegion's private key.

   

Eliptic Curve Cryptography ECC is the required algorithm for key encryption. RSA-encrypted keys may be accepted in limited circumstances.

Important: Two different sets of keys were just referenced - and there will be (at least) one more key discussed later in this guide. Keep that in mind; several keys are referenced throughout this guide, each with a specific purpose. To avoid confusion, rely on the name used to identify the key to differentiate it from the others.

The mutual trust established through use of the mTLS protocol ensures secure, trusted transmission of data between Allegion and partner systems. In order to communicate with Allegion APIs, key exchange must occur first between Allegion an the partner. You can either obtain keys from a Certificate Authority, or you can generate your own keys.

Note: If you've already exchanged keys with Allegion for other API integration projects then this step may already be completed. Talk to your Allegion Customer Success team to determine if Allegion already has an NFC Mobile Credential API mTLS certificate for your organization.

The instructions below detail a standard process for generating your own Partner mTLS API Keys using the OpenSSL Toolkit. If you already have a way to create and manage certificates and/or use CDN services such as CloudFlare you can use keys from those other services/providers instead of generating self-signed certificates.

The next section covers the process for sending Allegion your Partner mTLS Public API Key file, along with other details used to configure your API access.

3. Request Provisioning of a Schlage Mobile Credentials PACS Configuration

Once you have your mTLS tokens you can request Allegion Customer Success provision a Mobile Credentials PACS Configuration for your use. The Mobile Credentials PACS Configuration is a bundle of configuration settings applied in the Schlage Cloud that capture details related to your specific system requirements. Once a configuration is provisioned, you'll be granted the identifiers necessary to begin working with the Mobile Credentials Cloud API.

To request a Configuration, contact the Allegion Customer Success team to make the request. The team will work with you to collect information used to configure your environment and complete this request; if you have it up front you can provide it to them when requesting provisioning of your configuration:

• BitFormat - The bit format of the physical credentials you use today.
  

• Site Administrator - Email of the primary technical resource responsible for development on this project
  
  

• Credential Events API URL Endpoint - This is the API endpoint Allegion will use to send credential lifecycle-related events such as changes to the badge status or provision events.
  
  

• Organization Name (appears on pass) - This is the name of your organization as it will appear on the pass they download into their digital wallet.
  
  

• Default Patron Photo - A image to be used in the event your organization decides not to put employee photos in the pass. This photo image should conform to the User Photo specs as detailed in the Mobile Mobile Credentials Card Art Guide.
  




• Config card shipping address - A card containing site key information that must be applied to a lock in order for it to accept NFC mobile credentials.
  
  

• Partner mTLS API Public Key - The public key you generated in the section above (ec_public_cert.pemor whatever you named this file). The Allegion Customer Success team will work with you to accomplish secure transmission of your public key.

  
  

⚠️ Important: Do not send the private key file or certificate authority files to Allegion or anyone outside of your organization.



• Partner mTLS Certificate File - The certificate file you generated in the section above (ec_cert.ceror whatever you named this file).

  
  

• Issuer Claim for ID JWTs (JSON Web Tokens) - The value of the iss claim from ID Tokens generated by your IdM (Identity Management System) is used by the Mobile Credentials Cloud to validate user requests (based on the Open ID Connect standard). This will be a URL provided by your IdM and typically associated with your IdM tenant.

  
  
• Audience Claim for ID Token JWTs - The value of the aud claim from ID Tokens generated by your IdM is used by the Mobile Credentials Cloud to validate access requests (based on the Open ID Connect standard). This is often an auto-generated GUID supplied by your IdM and associated with a specific IdM Application.
  
  
  ⚠️ Important: The audience claim for Access Token JWTs should be set to AllegionAccessHub.
  
  



• IdM Public Key(s) in PEM Format - This is the public key supplied by your IdM that is used for encryption/decryption of JWT ID tokens and Access tokens generated by your IdM. Note: If your ID Tokens are signed using a different certificate than your Access Tokens, you'll need to provide both public keys in PEM format.
  
  It is preferred that JWTs be signed using ECDSA (ECC) instead of RSA keys, however both are acceptable.
  

  
  Important: This is a different key than either of the mTLS API Keys discussed in the previous section. This is NOT the Partner mTLS API Public Key you generated in the previous section, nor is it the Allegion mTLS API Public Key. This is a different key that will be supplied by your Identity Management Provider.
  
  The IdM Public Key (or keys if different between id and access tokens) will be used to validate users from your IdM when they attempt to log in to the mobile app used to deliver a mobile credential into their Apple Wallet. This key must be delivered in PEM format. This may be easily obtained from your IdM from the Well-Known Open ID Configuration details. For instance, if using Auth0, your PEM is likely accessible at https://[YOUR_IDM_DOMAIN]/.well-known/pem

  The IdM Public Key(s) is required at this step in order for Allegion to configure your API access; however, it is not used for any other purpose in Credential Lifecycle Management (the subject of this guide). This key will play an important role when your team is building the Mobile Credentials iOS app, covered here.

   

  Note that Allegion will assign unique Facility Codes for sites unless otherwise requested.
  
  

You'll receive a response to your request within 48 hours. The response - or a follow-up message if not all detail was provided in the initial request- will include the following information:

1. Integration ID - A GUID used to identify the Schlage integration you are targeting when making API calls to Allegion
   
   
2. Completed config card - A plastic card shipped to your address containing the aforementioned key information
   
   
3. Client ID - A GUID representing your application used when making API calls to Allegion
   
   

4. Allegion mTLS API Public Key - This is the public key from Allegion that your team will need to use to decrypt messages sent to you from Allegion. For convenience, Allegion will provide this key in bothPEM and CER formats. This key will allow you to fulfill the other side of the mTLS requirement covered in the section above, including when testing from tools such as Postman and when developing your production solution.

Once you have this information you are ready to begin development.

Building the Credential Events API

To support communication from Allegion to ACS Partner, the partner must build and expose a Credential Events API based on the details below.

API Base URL

The partner will send Allegion Customer Success the partner's Credential Events API base URL.

API Endpoints

The partner will need to host 3 API endpoints that can process POST requests sent from Allegion:

1. [baseURL]/v1/ping - this endpoint is suggested solely for connectivity testing between Allegion and the partner.
   
   
2. [baseURL]/v1/credentials/activate- Allegion will send Credential Delivery Events to this endpoint
   
   
3. [baseURL]/v1/credentials/manage- Allegion will send Credential Lifecycle Events to this endpoint

Note: To determine the base URL applicable for your integration, refer to the Vertical-specific Endpoints section above.

Authentication

As described above, Allegion requires the API exposed for event delivery support authentication and enforces mutual transport layer security (mTLS) to achieve authorized, secure connections between Allegion and the ACS partner:

1. Allegion Client Certificate - Allegion shall provide the ACS partner developer team with a client certificate (also known as a public key) during onboarding. This certificate will be included with requests when establishing a connection to the downstream system. The partner should validate that this client certificate matches the one provided out of band by Allegion when creating a session.

2. ACS Partner Client Certificate - During on boarding the partner shall also provide a certificate to Allegion. Allegion will use this certificate to validate all messages received from the partner before processing them.

Connectivity Testing

In order to validate connectivity between Allegion and the partner, Allegion provides a /partnerPing endpoint. Using both the partner ping endpoint and the Allegion ping endpoint, mTLS connectivity can be validated to ensure it is correctly configured. Here's how it works: Partners will send a POST request to the Allegion /partnerPing endpoint that validates inbound API calls (to Allegion) are correctly configured for mTLS. This inbound request will be processed by Allegion and a synchronous outbound request to the partner's /ping endpoint will be sent from Allegion to validate the outbound side of the mTLS interaction. The inbound request to the Allegion/partnerPing endpoint must include the partner's subscription key in the header (set asalle-subscription-key) and the clientId supplied by Allegion to the partner in the request payload as a JSON request:

{
    "clientId": "[CLIENT ID]"
}

The inbound call to Allegion can be sent to any vertical-specific base endpoint. Here's a sample inbound request using the Employee Badge QA vertical endpoint:

curl --location 'https://api.allegion.com/employeebadge/partnerqa/pacs/partnerPing' \
--header 'alle-subscription-key: [SUBSCRIPTION KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "[CLIENT ID]"
}'

Here's how the two ping endpoints work together to support mTLS connectivity validation:

1. The parter will make an inbound POST request to the Allegion /partnerPing endpoint with the clientId.

2. If an inbound mTLS connection is successfully established (from partner to Allegion), Allegion will use the integrationId supplied to the Partner during onboarding to make a new/separate, outbound POST request to the partner's corresponding /ping endpoint.

3. If the outbound mTLS connection to this second call is successfully established (from Allegion to partner), the partner should respond to the Allegion request - synchronously - with a 200 success response.

4. This 200 success response from partner to Allegion for the outbound request validates to Allegion that the inbound side of the mTLS connection is also properly configured, and Allegion will complete the originating inbout request by sending a 200 success response for the partner's original, outbound request in step 1. The diagram below illustrates the connectivity testing sequence.

Processing Events

There are two types of events sent by Allegion for processing by the PACS - Credential Delivery Events and Credential Lifecycle Events.

Credential Delivery Events

Credential Delivery events are sent from Allegion to the ACS Partner whenever a credential is successfully delivered to a user's digital wallet. Credential Delivery event payloads are structured as follows:

{
    "clientId": "[CLIENT ID]",
    "userId": "[USER ID]",
    "credentials": [
        {
            "credentialId": [CREDENTIAL ID]
            "formFactor": {
                "badgeId": "[BADGE ID]",
                "bitFormat": "[BIT FORMAT]",
                "facilityCode": "[FACILITY CODE]"
            },
            "deviceType": "iPhone" | "Android" | "Apple_Watch" | "WearOS"
        }
    ]
}

Payload details:

1. clientId- A string representing the Client ID assigned to your development team by Allegion as detailed above. Required.

2. userId - The user ID of the user on whose behalf an access right should be created.

3. credentialId - A generated GUID uniquely representing the newly created credential.

4. credentials[ formFactor ] - A container element for a single credential record inside an array holding the following required values:
   

   1. badgeId- A string representing the badge ID number of the user for who the badge will be created. Required.

   2. bitFormat- A string representing the bit format used to encrypt credentials for readers at the site where this mobile credential will be used. This will be the same bit format as is used today for physical credentials. Required.

   3. facilityCode- A string representing the facility code associated with the site where this credential will be used. This will be the same facility code as is used today for physical credentials. Required.

5. deviceType - The type of device used to make the credential request. Value will be iPhone, Android, Apple_Watch or WearOS (for an Android Wearable device).

   
   

These payloads by design may contain events for multiple credentials for a single user, such as is the case for users who have both mobile phone and watch devices. In such a case, each device has a unique credential.

Credential Lifecycle Events

Credential Lifecycle events are sent from Allegion to the ACS Partner whenever a credential lifecycle event occurs and must be processed by the ACS Partner, such as when a pass is suspended, resumed or deleted. Credential Lifecycle event payloads are structured as follows:

{
    "clientId": "[CLIENT ID]",
    "userId": "[USER ID]",
    "credentialId": "[CREDENTIAL ID]",
    "status": "suspend" | "resume" | "delete"
}

Payload details:

1. clientId- A string representing the Client ID assigned to your development team by Allegion as detailed above. Required.

2. userId - The user ID of the user on whose behalf an access right should be created.

3. credentialId - The unique identifier of the credential for which the event is relevant.

4. status - The credential lifecycle status for processing. Will be either suspend, resume, or delete

These events will be dispatched by Allegion to the ACS anytime a credential's lifecycle status changes in the mobile wallet and the update needs to be made and reflected in the ACS.

Note that once the event is dispatched to the ACS Partner, there is no response expected or processed by Allegion or the Digital Wallet provider regarding the successful processing of that event.

Creation, Activation and Assignment Lifecycle Operations

Use Cases Addressed: #1, #2, #3, #4, #5, #7, #9

The first operation that will be invoked when implementing support for mobile credentials is the credential creation operation. Credential creation is initiated by the Access Control System and will occur anytime an employee needs to be granted access to spaces secured by the ACS. The Access Control System is responsible for sharing and maintaining with Allegion Cloud a record of all valid employees that should have authorization to request a mobile credentials. The ACS will be responsible for informing the Allegion Cloud that a future inbound request from a valid user to create a new credential should be honored and processed. Note that this operation is called anytime BEFORE the user credential request is made from a mobile app - it is not part of that request and must be executed before that user request is made. The request will include details about the user as well as badge details such as badge ID for the credential ID that will be generated. Badge details are no different from details used when creating physical credentials today. This is an important point - the information used to create and manage physical credentials today does not change when creating mobile credentials.

To achieve this, the ACS will send a POST request the Allegion Cloud /provision endpoint to Create an Access Right record on behalf of each valid user. Access Rights represent a right by the user to request a mobile credential. Allegion Cloud will hold the Access Right record, and upon a user making a request to add a mobile credential to their wallet using a mobile app that includes the Allegion NFC SDK, Allegion will honor and process the request with the Digital Wallet Provider.

Here's a sample request to create an Access Right using the Employee Badge vertical base endpoint:

curl --location 'https://api.allegion.com/employeebadge/pacs/credentials/provision' \
--header 'alle-subscription-key: [API_SUBSCRIPTION KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "[CLIENT ID]",
    "requestedCredentials": [
        {   
            "userId": "roman.sebastian@romanworks.com",
            "firstName": "Roman",
            "lastName": "Sebastian",
            "accessClass": "An Access Class",
            "accountHolderNumber": "An Account Holder Number",
            "pacsTag": "ACS Provider Identifier",
            "patronBadgePhoto": "iVBORw0KGgoAAA.......BASE64EncodedImage"
        }
    ]
}'

A successful request will yield a 200 response with no response payload.

The request above includes all details necessary to create an Access Right in the Allegion Cloud on behalf of the user. This access right will be stored by Allegion Cloud and used at the time a user makes a request to download a mobile credential into their digital wallet. The request body details the following information about the access right:

1. clientId- A string representing the Client ID assigned to your development team by Allegion as detailed above. Required.

2. alle-subscription-key- A string representing the API Subscription Key assigned to your development team by Allegion as described above. Required. Note: Do not use the Mobile SDK Subscription Key here.

    

   ⚠️ Important: The API Subscription Key is different from the Mobile SDK Subscription Key

   As you build your Mobile Credentials solution, your team will be working with APIs and SDKs across two different projects. Each project outlines specific areas of development effort and uses a different subscription key to interact with Allegion. For this guide/project, we'll be focused on integration between an Access Control System and Allegion Mobile Credentials Cloud, so we'll be using an API Subscription Key.

   When building the mobile app that will deliver mobile credentials into a wallet (the subject of a different guide), a Mobile SDK Subscription Key is used. These are each different keys with different permissions, and are not interchangeable. Mixing/matching keys will result in errors and frustration, so we'll make this callout in several places throughout this and other guides.

    

3. userId - The user ID of the user on whose behalf an access right should be created. Required. This is a key field, and there are a few important rules that must be adhered regarding this value:
   

   • This value MUST be an email address.
   • The email address MUST match an email address that uniquely identifies the user in the corporate Identity Management System.
   • This email address MUST also be able to be used to correlate to a unique user in the Access Control System. In other words, the ACS will need to be able to use userId to uniquely identify an ACS user.
     
   
   

   The userId value is an important value because it serves as a unique identifier across all systems.
   
   

4. firstName- A string representing the first name of the user for who the badge will be created. Not Required.

5. lastName- A string representing the last name of the user for who the badge will be created. Not Required.

6. accessClass- A string representing the access class associated with this user/pass. Examples include "Employee", "Student" and "Faculty". Not material to creation of the mobile credential. Not Required.

7. accountHolderNumber- A string representing the account holder number associated with this user/pass. Not material to creation of the mobile credential. Not Required.

8. patronBadgePhoto- A base64-encoded image of the patron, sized according to specfications detailed in Pass Details section of the Mobile Credentials iOS Card Art Guide. For test purposes, images can be manually encoded using any of a number of public sites that do the job such as this one. Not Required. Be aware that there is a 50kb limit on the size of images sent to Allegion for processing badge photos.

After a successful Create Access Rights call, the Allegion Cloud will honor a request for this user to add a badge to their digital wallet as illustrated by the high-level diagram below:

For this mobile app interaction to be successful, the Create Access Rights call must have been made at some point before the mobile app requests to add a pass to the wallet. This flow is covered in the How-To Guide for Building a Schlage NFC Mobile Credentials App for iOS or the How-To Guide for Building a Schlage NFC Mobile Credentials App for Google Wallet.

With the addition of the pass to the digital wallet, this flow addresses use cases #7 and #9, and a Credential Delivery event will be dispatched from Allegion to the ACS.

Update Operations

Use Cases Addressed: #6

Update operations are requests from the ACS to Allegion Cloud used to make a change to user details for an existing pass, such as name or badge photo. This is a straight-forward operation and is always initiated by the ACS.

Update operations are executed using the /update endpoint. Here's an example request using the Employee Badge vertical base url:

curl --location 'https://api.allegion.com/employeebadge/pacs/credentials/update' \
--header 'alle-subscription-key: [API_SUBSCRIPTION KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "[CLIENT ID]",
    "userId": "roman.sebastian@romanworks.com",
    "firstName": "Roman",
    "lastName": "Sebastian",
    "accessClass": "An Access Class",
    "accountHolderNumber": "An Account Holder Number",
    "patronBadgePhoto": "iVBORw0KGgoAAA.......BASE64EncodedImage"
}'

The userId is the key on which the user record to be updated will be identified.

A 200 response from this call represents a valid request was made to instruct Allegion Cloud to dispatch the update with the Digital Wallet Provider. There is no follow-up event from the Digital Wallet provider today to confirm the update was applied.

Suspension, Resumption and Deletion Credential Lifecycle Operations

There are a number of reasons a pass may need to be suspended, resumed or deleted. Two of the fifteen use cases from above (#10 - User-initiated suspend and #13 - Partner-initiated suspend) identify scenarios where a suspend event should be induced and/or processed, but each identifies a different source for the request. Suspend, resume and delete credential lifecycle operations are invoked and processed using both the Schlage Mobile Credential PACS API and the Credential Events API.

For use case #13, someone at the site responsible for managing building access will use an ACS partner tool such as a management dashboard to mark a pass as suspended. This kind of event could be due to scenarios such as temporary office lockdown or employee leave of absence. In this scenario, the Credential Events API allows the ACS to make the request to Allegion to suspend, or resume, a pass in the wallet. Allegion will process the request in conjunction with the Digital Wallet Provider and ensure the pass is suspended. Once suspended, the pass will be designated as invalid for use until it is resumed.

For use case #10, the user - not the ACS partner - is requesting that the mobile credential should be suspended - typically related to events such as when a phone containing a mobile credential is lost or stolen. In this case, a request will be initiated on the user's mobile phone and sent to the Digital Wallet Provider for processing, which will in turn forward the suspend request to Allegion. Allegion will then forward the event on to the ACS.

This is important; in order for the ACS to receive the message a mechanism must exist for this purpose. Because Allegion works with many different ACS providers, the Credential Events API pattern has been defined and documented to support a standard approach for ACS providers to implement to process events sent by Allegion. This pattern will be used anytime Allegion needs to send a credential lifecycle-related event to the ACS that was sourced from a Digital Wallet Provider. The diagrams below illustrate the sequence of activities for user-initiated suspend, resume and delete operations.

Partner-initiated Suspend/Resume/Delete Operations

Use Cases Addressed: #8, #13, #14, #15

Partner-initiated suspend, resume and delete operations use the /manage endpoint. The user for which the request is made must already have an access right created on their behalf before this request will be successfully processed.

This request can be initiated using either the credentialId as the key or using a combination of the userId, clientId and badgeId. Below are examples of each method:

Using credentialId as identifier

A sample request to process a partner-initiated suspend, resume or delete operation is below. Here's an example using the Employee Badge vertical base URL:

curl --location 'https://api.allegion.com/employeebadge/pacs/credentials/manage' \
--header 'alle-subscription-key: [API_SUBSCRIPTION KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
      "credentialId": "[CREDENTIAL ID]",
      "action": "[SUSPEND | RESUME | DELETE]"
    }'

This request includes all details necessary for a partner to suspend or resume a user's badge in the Digital Wallet. The request body details the following information for a request:

1. alle-subscription-key- A string representing the API Subscription Key assigned to your development team by Allegion as described above. Required. Note: Do not use the Mobile SDK Subscription Key here.

2. credentialId - The user ID of the user on whose behalf an access right should be created.

3. action- A string representing the requested action. There are two options:

   • Use SUSPEND to suspend a credential
   • Use RESUME to resume a credential
   • Use DELETE to delete a credential

Using userId, clientId and badgeId as combination identifier

A sample request to process a partner-initiated suspend, resume or delete operation is below using the Employee Badge vertical base URL:

curl --location 'https://api.allegion.com/employeebadge/pacs/credentials/manage' \
--header 'alle-subscription-key: [API_SUBSCRIPTION KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
      "clientId": "[CLIENT ID]",
      "userId": "roman.sebastian@romanworks.com",
      "badgeId": "1045",
      "action": "[SUSPEND | RESUME | DELETE]"
    }'

This request includes all details necessary for a partner to suspend or resume a user's badge in the Digital Wallet. The request body details the following information for a request:

1. alle-subscription-key- A string representing the API Subscription Key assigned to your development team by Allegion as described above. Required. Note: Do not use the Mobile SDK Subscription Key here.

2. clientId- A string representing the Client ID assigned to your development team by Allegion as detailed above. Required.

3. userId - The user ID of the user on whose behalf an access right should be created.

4. badgeId- A string representing the badge ID number of the user for who the badge will be suspended or resumed.

5. action- A string representing the requested action. There are two options:

   • Use SUSPEND to suspend a credential
   • Use RESUME to resume a credential
   • Use DELETE to delete a credential

User-initiated Suspend/Resume/Delete Operations

Use Cases Addressed: #10, #11, #12

User-initiated suspend, resume and delete operations use a different pattern than partner-initiated requests and must be received and processed by the ACS partner system instead of being initiated by that system. This is because in user-initiated operations, the request comes from the user (via the Digital Wallet Provider) and flow to Allegion and the PACS partner instead of the other way around.

User-initiated suspend, resume and delete operations are serviced by events dispatched from Allegion to the ACS Partner's Credential Events API. and flow documented therein.

Best Practices for Creating Access Rights

This section covers typical models for supporting this new feature in a mobile app experience.

Creating an Access Right for a user is the first operation that must be completed in the Credential Management Lifecycle. From there, a credential can be added to the wallet app...but when should the access right be created?

There are a few options for how the user will initiate provisioning of their credential.

One flow option is to allow the user to initiate the request from an existing (PACS or customer) mobile app, which in turn would result in a request to create a new credential record for the user in the ACS and generate a new digital credential in the Schlage Cloud for dispatch to the wallet on the user's device.

Another flow option is that the Access Control Administrator may decide to generate credentials for a user first, and then notify the user to download the app used to provision the credential into the wallet.

In either scenario, the ACS must initiate a Create User Access Rights (Provision) API request to the Schlage cloud in order for the credential to be generated and provisioned as described above.

As mentioned, a typical flow for adding a credential to wallet might go as follows:

1. The user will download and open the PACS provider's, their organization's app or the Schlage Mobile Access App.
   
   
2. The user will log in to the app. The app will challenge the user using a standard OAuth 2.0-based SSO authorization model.
   
   
3. After logging in (and depending on app navigation design), the user will be able to get to an area where the app will offer the option to add a mobile credential to their digital wallet.
   
   
4. Upon choosing to add the mobile credential, the Access Control System should generate a new credential record for the user and then make the API call above to initiate creation of access rights and a mobile credential by Schlage Cloud platform. From there, a series of cloud and device-based interactions involving Allegion Cloud, the Allegion Mobile Credential SDK, the Access Control System and Apple/Google will result in the generation of a new credential and dispatch of the credential back to the mobile device for provisioning into the device digital wallet. These interactions include user validation, credential generation and credential synchronization steps across these systems. If a watch is paired with the device, an additional credential will also be generated for that device.
   
   
5. Upon receiving the credential, the mobile device will provision the credential into the digital wallet using the Schlage Mobile Credential SDK.
   
   
6. Once in the wallet, the mobile credential can be used using standard NFC-based interactions with organization locks and readers. Access will continue to be managed through the Access Control System just as the organization conducts for existing credentials.

Based on this flow, it is up to the ACS Partner to determine if access rights should be created in bulk and up front or if they should be created on-demand when the user downloads and logs into their app. Either approach can be supported by Allegion; access rights do not expire and will support the process of adding a credential to a digital wallet regardless of how early an access right was created.