Mobile No-Tour

This document is intended to be consumed by partners who have already implemented and are familiar with No-Tour for plastic credential integration.

Mobile Credential Overview

Schlage Mobile Access Credentials allow the physical access credential cards or fobs normally carried by a patron to be replaced with a mobile credential that is embedded in the patron’s mobile phone. These mobile credentials use Bluetooth Low Energy to communicate with ENGAGE™ Mobile enabled devices. Some Physical Access Control Solution (PACS) providers have built their own patron mobile app and have consumed the Schlage Mobile Access SDK which allows the Schlage Mobile Access Credential to be managed through the PACS patron mobile appOther PACS, who have not developed a patron mobile app, utilize the Schlage Mobile Access Application to manage the Schlage Mobile Access Credentials.

 

Allegion Developer Portal

 

Mobile Access Products and Features Explanation

Below is a table that outlines the core functionality of the Schlage Mobile Access software products.

CapabilityMobile CredentialNo-Tour BasicAPI Only Basic
Best in Class SecurityYesYesYes
Communication Technology UsedBLEBLEBLE
Allows Partner to Build their Own AppYesYes
Allows Partner to leverage Schlage Mobile Access ApplicationYes
Allows No-Tour Capability via Mobile AppYesYes
Unlimited No-Tour UpdatesYesYes
Only one Active No-Tour Update Allowed, per User, per LockYesYes
Timing and AvailabilitySeptember 2020July 2021November 2023
Distribution ChannelDirect to Software PartnerDirect to Software PartnerDirect to Software Partner

 

“Mobile Credential” is intended for customers that do not need the functionality of No-Tour. 

“No-Tour Basic” builds upon the “Mobile Credential” API by providing basic No-Tour functionality. With “No-Tour Basic” patrons can be given access to an unlimited number of doors; however, a patron may only use No-Tour capabilities for that patron. Patron A cannot carry Patron B’s updated access rights. In “No-Tour Basic” the 11-sector limit that exists in the plastic credential world is now removed. 

No-Tour for Mobile Credentials

With the addition of No-Tour capability for mobile credentials, the property administrator is no longer required to tour the door for access updates or use an enrolment reader to program the mobile credentials. The access updates (commands/No Tour Payloads) can be retrieved on the patron’s phone and presented to the lock. 

Patrons with Schlage Mobile Access Credentials that utilize No-Tour functionality will no longer need to use physical credentials to gain access to their assigned doors, however software partners may choose to continue to use plastic credentials as-is.

Pre-requisites

  • Mobile SDK that supports Mobile No-Tour
    • SDK can be downloaded from the private GitHub. Please contact Allegion support to request access.
    • Detailed technical documentation, method definitions and sample code are included in the SDK itself.
  • Lock Firmware that supports Mobile No-Tour
    • Update the lock to minimum version that supports Mobile No-Tour

Lock Model

Firmware Version

LEBMB/LEBMS/LEBMD

03.08.06

NDEB

03.08.06

BE467B/FE410B

04.09.02

CTE

01.06.04

MTB11/MTB15/MTKB15

60.47.18

 

  • Subscription to Schlage Mobile Credentials in Allegion Developer Portal
    • Getting your subscription key

Every request made to the Mobile Credential API must include your subscription key for the "alle-subscription-key" property in the HTTP request header.

To find your subscription key, click on your profile link on the top of this page as seen in this screenshot:

Allegion Developer Portal

 

Your profile page provides access to subscription keys for all corresponding product subscriptions.

To see a subscription key for a product, click on “show” next to the key.

To regenerate a subscription key, click on the regenerate text next to the key.

 

Allegion Developer Portal Profile

 

  • Authentication Token (Bearer Token)
    • Generating the token

To get an authentication token a POST call is made with username and password. The authentication token expires in 10 hours.

Sample request:

curl -v -X POST "https://api.allegion.com/SMC/Authentication/Tokens"

-H "Content-Type: application/json"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii "{

"username": "xxxxxxxx",

"password": "xxxxxxxx"

}"

The response from the POST call above will be a 200 (OK) with Token, Token Type and Expiry created in the response. The Token from the response must be sent in the HTTP Authorization Header in any authenticated API request.

Sample response:

{

        "token": “xxxxxxxxxx”,

        "tokenType": “Bearer”,

        "expiresIn": 86400

}

Refer to Authentication Token API in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

Before we get into the details of how to create No-Tour Payloads, let us understand how to work with mobile credentials.

Working with Mobile Credentials

  • Creating a Mobile Credential

The first thing you'll need to begin working with Mobile No-Tour APIs is a mobile credential. No-Tour Payloads will be associated to a mobile credential created for a given User ID.

The following call will create a mobile credential:

Sample request:

curl -v -X POST "https://api.allegion.com/SMC/credentials/mobile"-H "Authorization: Bearer {Token}"-H "Content-Type: application/json"-H "Accept: application/json;version=1"-H "alle-subscription-key: {subscription key}"

--data-ascii "{

"UserId": "1a8e4e48-3727-4eb6-a8a5-a99384ff4a9b",

"CardFormat": "48X",

"CardNumber": 1,

"FacilityCode": 20,

"IssueCode": 1,

"CredSector": 1,

"Attributes": {

"SiteId": "123456",

"SiteName": "My Site Name"

}

}"

The response from the POST call above will be a 201 (CREATED) with Credential ID created in the response.

Sample response:

{

  "credentialId": "00000000-0000-0000-0000-000000000000"

}

Refer to ‘Create Credential API’ in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

  • Deleting Mobile Credential

You may end up having credentials that you want to delete when you remove the patron. Use the API to delete the unused mobile credential. Depending on the pricing you choose, you may be charged for each active credential, so it is important to delete un-used credentials.

To delete a mobile credential, you can use a DELETE call, specifying the User ID or Credential ID in the URL:

  • the /SMC/credentials/mobile/{credentialId} endpoint: to delete credential by Credential ID

Sample request:

curl -v -X DELETE "https://api.allegion.com/SMC/credentials/mobile/{credentialId}"

-H "Authorization: Bearer {Token}"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii ""

The response from the DELETE call above will be a 204 (NO CONTENT) with an empty response, and the credential will be deleted.

Sample response: Empty

Refer to Delete Credential in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

  • the /SMC/credentials/mobile/users/{userId} endpoint: to delete credential by User ID

Sample request:

curl -v -X DELETE "https://api.allegion.com/SMC/credentials/mobile/users/{userId}"

-H "Authorization: Bearer {Token}"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii ""

The response from the DELETE call above will be a 204 (NO CONTENT) with an empty response, and the credential will be deleted.

Sample response: Empty

Refer to Delete Credential by UserId in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

  • Listing Mobile Credential

To begin working with mobile credentials for Tour or No-Tour access updates, let's first learn how to list existing mobile credentials. (If you have not already created a mobile credential, please see the Creating a mobile credential section.) 

  • Get Credential

If you'd like to see the details of a mobile credential that have been created against a credential ID, you can make a GET mobile credential call by providing the Credential Id.

Sample request:

curl -v -X GET "https://api.allegion.com/SMC/credentials/mobile/{credentialId}"

-H "Authorization: Bearer {Token}"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii ""

The response from the GET call above will be a 200 (OK) with the below response.

Sample response:

{

  "credentialId": "00000000-0000-0000-0000-000000000000",

  "userId": "00000000-0000-0000-0000-000000000000",

  "payloadType": "string",

  "rawData": "string",

  "cardFormat": "string",

  "cardNumber": 0,

  "facilityCode": 0,

  "issueCode": 0,

  "isDownloaded": true,

  "attributes": {}

}

Refer to Get Credential API in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

  • Get Credential by User ID

If you'd like to see the details of mobile credentials that have been created for a patron, you can make a GET mobile credential call by providing the User Id.

Sample request:


curl -v -X GET "https://api.allegion.com/SMC/credentials/mobile/users/{userId}"

-H "Authorization: Bearer {Token}"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii ""

The response from the GET call above will be a 200 (OK) with the below response.

Sample response:

[

{

  "credentialId": "00000000-0000-0000-0000-000000000000",

  "userId": "00000000-0000-0000-0000-000000000000",

  "payloadType": "string",

  "rawData": "string",

  "cardFormat": "string",

  "cardNumber": 0,

  "facilityCode": 0,

  "issueCode": 0,

  "isDownloaded": true,

  "attributes": {}

}

]

 

Refer to Get Credential By User ID API in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

  • Get All Credentials

If you'd like to see the list of existing mobile credentials that have been created, you can make a GET all mobile credential call.

Sample request:


curl -v -X GET "https://api.allegion.com/SMC/credentials/mobile

-H "Authorization: Bearer {Token}"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii ""

The response from the GET call above will be a 200 (OK) with the below response.

Sample response:

[

{

  "credentialId": "00000000-0000-0000-0000-000000000000",

  "userId": "00000000-0000-0000-0000-000000000000",

  "payloadType": "string",

  "rawData": "string",

  "cardFormat": "string",

  "cardNumber": 0,

  "facilityCode": 0,

  "issueCode": 0,

  "isDownloaded": true,

  "attributes": {}

}

]

Refer to Get All Credentials API in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

Working with Mobile Credentials for No-Tour

Now that you've created a mobile credential, you can start working on building No-Tour Payloads.

For a patron to receive a mobile no-tour command, they must first have a mobile credential assigned to them. The No-Tour payload can then be created against the Credential ID generated from creating the patron’s mobile credential.

For information on how to create the No-Tour payloads, please refer the documentation for No-Tour integration for plastic credentials or reach out to your Allegion Integration Engineer.

  • Saving No-Tour Payloads for a mobile credential

No-Tour Payloads can be created for a mobile credential for one or multiple devices and can be saved to Allegion Cloud using this endpoint.

You may end up having No-Tour Payloads that you want to update when you want to revise the access. In such scenario, save the updates again.

The request to save a No-Tour Payload can be made using a POST call, specifying Credential ID in the URL:

Sample request:

curl -v -X POST "https://api.allegion.com/SMC/credentials/mobile/{credentialId}/NoTour"

-H "Authorization: Bearer {Token}"

-H "Content-Type: application/json"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii "{

  "NoTourPayloadDetails": [

    {

      "LockId": 1234,

      "SerialNumber": "EjRWeJq83vEjRWeJq83vEg==",

 "NoTourPayload": "123456789ABCDEF123456789ABCDEF123456789ABCDEF123456789ABCDEF123456789ABCDEF123456789ABCDEF123456"

    }

  ]

}"

In the above sample:

  • LockId is the unique device ID identifying the Device/Lock within your Site or Facility
  • SerialNumber is the Device Serial Number identifying the Device/Lock which is unique across all devices
  • NoTourPayload is the credential payload that contains access commands

Both LockId and SerialNumber are required in the request. The Lock processes the No-Tour Payloads received from the SDK. LockId is analogous to directory sector in the plastic world. SerialNumber is required to uniquely identify a Lock across the ENGAGE system.

The response from the POST call above will be a 201 (CREATED) with an empty response, and the No-Tour Payloads will be saved for a Credential ID..

 

Sample response: Empty.

You can create No-Tour Payloads against a credential for one or multiple devices/locks. 

For example, Alex is a resident of Unit 101 in XYZ's multi-family residence. Alex needs access to the facility's main entrance (Door 1) and Unit 101 (Door 2). The facility administrator assigns Alex’s mobile credential access for Door 1 and Door 2.

In the above example, you can create No-Tour Payloads for Door 1 and Door 2 for Alex’s mobile credentials and save to Allegion Cloud. You cannot associate the No-Tour Payload of another resident of Unit 101 or another user of the facility's main entrance to Alex’s mobile credential.

Refer to Save No-Tour Payloads for CredentialId API in SchlageTM Mobile Credentials product for detailed API method documentation.

  • Deleting No-Tour Payloads

You may end up having No-Tour Payloads that you want to delete when you want to revise the access. Please note that this can be performed before the patron has downloaded the latest updates (No-Tour Payloads) on the phone by calling in to the Allegion cloud. If the undesired access updates are downloaded on the patron’s phone, they will be presented to the device/lock on the next access attempt by the user.

One way of removing the undesired No-Tour payloads from the patron’s phone is by deleting the credential and the patron’s mobile application calls in to the Allegion cloud. This way, the patron’s mobile credential and the corresponding No-Tour Payloads are removed from the patron’s phone.

  • Delete No-Tour Payloads by Credential ID

The request to delete No-Tour Payloads can be made using a DELETE call, specifying Credential ID in the URL:

Request template:

curl -v -X DELETE "https://api.allegion.com/SMC/credentials/mobile/{credentialId}/NoTour"

-H "Authorization: Bearer {Token}"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii ""

The response from the DELETE call above will be a 204 (NO CONTENT) with an empty response, and the all No-Tour Payloads associated with the Credential ID will be deleted.

 

Sample response: Empty

Refer to Delete No-Tour Payloads by Credential Identifier‘ in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

 

  • Delete No-Tour Payloads by Device Serial Number:

The request to delete No-Tour Payloads can be made using a DELETE call, specifying Device Serial Number in the URL:

Request template:

curl -v -X DELETE https://api.allegion.com/SMC/credentials/mobile/NoTour/Device/{deviceSerialNumber}"

-H "Authorization: Bearer {Token}"

-H "Accept: application/json;version=1"

-H "alle-subscription-key: {subscription key}"

--data-ascii ""

The response from the DELETE call above will be a 204 (NO CONTENT) with an empty response, and all the No-Tour Payloads associated with the Device Serial Number will be deleted.

Sample response: Empty

Refer to Delete No-Tour Payloads by Device Serial Number in SchlageTM Mobile Credentialsproduct for detailed API method documentation.

What these APIs allow?

  • Saving No-Tour payloads per patron per Device/Lock. Only one credential can be assigned to a patron. However, the credential can have No-Tour payloads for multiple Device/Locks
  • Deleting No-Tour payloads per credential

What these APIs do not allow?

  • Multiple credential assignment to a patron
  • Multiple No-Tour payloads per credential per Device/Lock
  • Delivery status of the payloads
  • Updating a No-Tour payload that is already sent to our API. Revision of payloads can be achieved by saving the payload to the Allegion Cloud again
  • Payload downloaded on a mobile device cannot be deleted. New payloads need to be created to revise undesired payloads

Things to Note

  • Unlike plastic credentials which contain jagSectors in its No-Tour JSON, mobile credentials contain No-Tour Payload
  • Unlike plastic, there is no sector limitation in mobile credential. Hence Group ID is not used in mobile credential
  • Since there is no Group IDs which are used to assign multiple devices to a group, Master Credential concept based on Group ID does not apply to mobile credential
  • The mobile app consuming the mobile No-Tour functionality should check in to the cloud to retrieve the latest No-Tour payloads before sending the payloads to the lock failing which the last downloaded payloads are delivered to the lock

Best Practices

  • To enable No-tour, a physical tour of the locks and readers is necessary for configuration.
  • No-tour can be used to add, update and block credentials but cannot be used to remove a credential from a lock/reader. Even if a credential is put in a blocked state, the credential remains on the lock/reader. This can cause a buildup of blocked credentials that can only be removed by touring the lock.
  • If using multiple users/credentials in one app, keep in mind that we do not store no-tour payloads. This means that when a user pulls their access payload and no-tour payload and this user doesn't get to use their no-tour payload before they switch to another user/credential, then that no-tour payload is lost.
  • When looking to remove access using no-tour you must send a no-tour payload with a status of “blocked”. Simply deleting a no-tour payload does not remove access from the lock, only deletes the payload.
  • After a credential is blocked, either by tour or no-tour, the only way to regain access for the credential on the lock is to tour the lock.
  • The PACs partners mobile app should check in to the Allegion cloud to retrieve the most recent no-tour payload before sending payloads to the lock.
  • PACS Partners are responsible for mapping UserId from the credential APIs to UserRefId of no-tour command in their software.

Frequently Asked Questions

  1. Q. What is the “Accept” value supposed to be in "Save No-Tour Payloads for CredentialId” API?

            It is the Media type which is specified in the request header as an attribute i.e. the format of the data as type/subtype e.g. text/html, text/xml, application/json, image/jpeg etc. In HTTP request, Media type is specified in the request header using Accept and Content-Type attribute. The Accept header attribute specifies the format of response data which the client expects and the Content-Type header attribute specifies the format of the data in the request body so that receiver can parse it into appropriate format.API developers would have the knowledge about what these attributes stand for.The value for “Accept” is auto-populated in Dev Portal. The value is “application/json;version=1”

    Q. What is the format of the “serialNumber” tag? The schema documentation just says “string.” Is it 16 or 32 characters? ASCII or Base64??

            The Lock advertises the serial number in base64 encoded String. For example: AAAAAAAAAACiAAAADxUXjA== In the Engage MAPP we show the serial number in the HEX format. For example: A20000000F15178C In the API request, the PACS Partner are expected to send the same value the lock advertises i.e. the base64 encoded String.

    Q. How is the “noTourPayload” 96 byte tag string value formatted?

            NoTourPayload attribute is expected to have exactly 96 characters NOT 96 bytes. A HEX string of 96 characters constitutes 48 bytes which is equivalent to information held in 1 sector. 1 sector can have a maximum of 2 ADD credential Commands (1 ADD command equivalent to 24 bytes) OR 4 BLOCK (1 BLOCK command is equivalent to 10 bytes) OR 2 BLOCK 1 ADD OR 1 BLOCK 1 ADD OR 1 ADD OR 1 BLOCK This is same as how commands are constructed in plastic credentials. The NoTourPayload is of 96 characters (48bytes).

    Q. Do you have to load 2 Save No-Tour Payloads for Credential ID? Do both payloads have to include a sector 2? Since there are 2 payloads, will this take 6 seconds to complete?

            Sector 2 is directory sector, and it is not applicable to mobile credentials.

    Q. For No Tour using on a plastic credential each 48-byte sector is encrypted with the site key (CBC, IV=0), is this the same for NoTour on a mobile credential?

            Yes

    Q. What is the “Accept” value supposed to be in “Delete No-Tour Payloads by CredentialId” API?

            Same as explained above for "Save No-Tour Payloads for CredentialId” API

    Q. The “deviceSerialNumber” tag value says that it “must be URL encoded.” Is that the same 16 ASCII character string shown in the ENGAGE mobile app??

            Same as explained above for "Save No-Tour Payloads for CredentialId” API

    Q. What is the “Accept” value supposed to be?

            Same as explained above for "Save No-Tour Payloads for CredentialId” API

    Q. When a “Delete Credential” or “Delete Credential by UserId” API is successfully executed are all associated No-Tour payloads (if any exist) also deleted?

            Yes

    Q. When a “Get All Credentials”, “Get Credential”, or “Get Credential by UserId” API’s are executed does the response supply any information about any No-Tour payloads associated with that credential? If no, is there any way to determine what No-Tour payloads are currently associated with a credential?

            No, it does not supply any information about any No-Tour payloads associated with that Credential. No, currently there is no way to determine what no tour payload are associated with that credential

    Q. What is the Difference between UserId in Credentialing API and UserRefId in No-Tour Command in “Create Mobile Credential” API?

            Datatype of UserId for credentialing API is Guid where as UserRefId mentioned in the No-Tour commands are of Integer data type. The UserId is used to associate a mobile credential with the user where as the userRefId is used to associate a user to a No-Tour Command.

    Q. Do PACS Partner need to map the UserId (which is a GUID used when provisioning a credential via Credentialling API) and the userRefId (which is an int value used in No Tour Command) together?

            Yes, it is the responsibility of the PACS partner to manage a mapping between UserId of credentialing API and UserRefId of No-Tour command in their software