Mobile Identities v2.2
HID Origo Mobile Identities is a cloud service that provides trusted virtual credentials for authentication to physical access and extended applications in workplaces. The API enables developers to integrate administration capabilities such as user, device and credential management into custom applications.
This document provides a high level overview of the system and a specification for the API, version 2.2.
Architecture
The following image provides an overview of the solution architecture:
| Entity | Description |
|---|---|
| Custom Application | Your application, interfacing with the HID Origo Mobile Identities API to manage user enrollment and credential provisioning and lifecycle management. Your application may also, optionally, subscribe to callback events to receive information about state changes for users, devices and credentials. |
| HID Origo Mobile Identities API | The API described in this document. |
| Identity Provider | The system used for authentication. Your application interfaces with this system to generate authentication tokens. Refer to Authentication for more information. |
| Mobile App | A mobile app embedding the HID Origo Mobile SDK, such as the HID Mobile Access app. |
Invitation and Device Lifecycle
An Invitation Code typically goes through the steps outlined below. For this sequence, it is assumed a user record already exists.
| Step | Action | Description |
|---|---|---|
| 1 | Create Invitation Code | The application requests creation of an Invitation Code. At this point a Mobile ID can also be attached to the Invitation Code. |
| 2 | Return Invitation Code | Invitation Code status: PENDING. |
| 3 | Distribute Invitation Code | This can happen using any channel, such as through Push Notification. Distribution via email is supported directly in the API (provided user has an email address) |
| 4 | Acknowledge Invitation Code | Invitation Code is entered into an app embedding the HID Origo Mobile SDK. Depending on the result, the Invitation Code status changes to: ACKNOWLEDGED | NOT_SUPPORTED | FAILED. If the Invitation Code redemption is successful, a Credential Container resource is created and will eventually reach an ACTIVE state. Mobile IDs can only be issued to Credential Containers which in the ACTIVE state. |
| 5 | Callback Event | If the application has subscribed to callback notifications, Invitation Code status updates will be provided as part of a callback Notification in the invitations field. Credential Container status changes are provided in the credentialContainers field. |
Mobile ID Lifecycle
For this sequence, it is assumed the Credential Container is in ACTIVE state. Mobile IDs can however be attached to an Invitation Code through properties on the UserAction object.
| Step | Action | Description |
|---|---|---|
| 1 | Issue Mobile ID | The application requests issuance of a Mobile ID to a specified Credential Container. |
| 2 | Prepare Mobile ID | HID Origo makes the Mobile ID available for download. |
| 3 | Return Card Number | The Card Number for the allocated Mobile ID is returned. Credential status: ISSUE_INITIATED. |
| 4 | Mobile App Downloads Mobile ID | The Mobile App must initiate a connection to download the Mobile ID. With the HID Mobile Access app, this is initiated through a push notification. For custom apps using the HID Origo Mobile SDK, other mechanisms can be implemented. |
| 5 | Callback Event | If the application has subscribed to callback notifications, Mobile ID status updates will be provided as part of a callback Notification in the credentials field. Successful delivery of a Mobile ID is reported through the ISSUED status. |
| 6 | Revoke Mobile ID | Once a Mobile ID is in the ISSUED state, it can be revoked using the DELETE method against a specified {credential_id}. This operation automatically happens if either the User or Credential Container is deleted. |
| 7 | Mobile App Downloads Revoke instruction | The Mobile App must initiate a connection to download the Mobile ID revoke instructions. |
| 8 | Callback Event | If the application has subscribed to callback notifications, the Mobile ID REVOKE_INITIATED and REVOKED callbacks will be provided. If the operation is not successful, for example because the device is offline, the REVOKING_FAILURE status may be returned. |
Specification
The Mobile Identities API version 2.2 is provided as an OpenAPI specification below. Additionally, a PDF version is made available for reference.
Note
Some functionality is currently not available in the Partner Integration environment.
What's New
October 2021
- Added optional
phoneNumbersfield for Users - Added
hceCapabilityfield for Credential Containers - Deprecated Callback APIs: Refer to Events and Callbacks API
August 2023
- Support for additional fields(Email Address, Phone Number, Web Page URL, and the Font Color) to be displayed at the back of the card for Mobile Access for API customers (2.2)
January 2024
- What’s new in version
- MA 2.0 API Shutdown Implementation Steps.
- Customers in 2.1 or 2.2 who do not include content-type/Accept in the request headers are affected.
Glossary
| Term | Definition |
|---|---|
| Application-ID | The Application Identifier is used to identify an application calling HID Origo APIs. This value is provided by HID Partner Services. Please refer to Authentication for additional details. |
| CorrelationId | HTTP header returned for most requests, which should be included, in addition to timestamps, when logging support requests. |
| Credential Container | A device that is capable of storing Credentials, for example, mobile phones, tablets and wearables. Credential Containers are registered by consuming an Invitation Code in an application embedding the HID Origo Mobile SDK. Also referred to as device, mobile device, endpoint. |
| Invitation Code | Invitation Codes are issued to users as the first step in registering a new device (see Credential Container). Invitation Codes consist of a 16-character alphanumerical sequence and are used to authenticate devices and associate them with the relevant user. Also referred to as Invitation, UserInvitation. |
| Mobile ID | Virtual representation of a Seos® credential, stored securely within a Credential Container. Also referred to as Credential. |
| Part Number | A Part Number refers to a type of Mobile ID available for issuance for a given organization. One organization may have one or many Part Numbers available for selection. The Part Numbers available for an organization are listed in the 'Mobile IDs' section in the portal. Each Part Number has a reference, such as "MOBILE-ID_FTPN_1000" or "CRD633ZZ-01234", which is referenced when requesting issuance of Mobile IDs. |
| SCIM | System for Cross-Domain Identity Management: a widely adopted specification for managing user identities in cloud-based applications. SCIM Overview |
Known Limitations
The following is a list of known limitations with the current release of the HID Origo Mobile Identities API:
- The
AcceptHTTP header only has limited support.Content-Typeshould be included with requests without a payload to control versioning of the API. - The
cardNumberproperty may be both ofstringandnumbertype depending on endpoint called. - If the
descriptionfield is included in the list ofattributeswhen searching for Part Numbers, the field will be namedundefinedin the response. - Photo ID: The returned
Content-TypeHTTP header isimage/jpgforpngimages - Search API Restriction: All Search API endpoints impose a limit of 20,886 characters on the filter set.
Steps for Version Upgrade
API life cycle
| API version | Life Cycle Status | Dates | Comments |
|---|---|---|---|
| 2.2 | General Availability | - | Supported |
| 2.1 | General Availability | - | Supported |
| 2.0 | Deprecated | September 17, 2022 | Limited support. Will retire on February 29, 2024 |
2.0 API Shutdown Implementation Steps
MA API 2.0 Customers: (Applicable to all APIs)
- Migrate the MA API 2.0 customers to MA API 2.2. Refer Upgrade from 2.0 to 2.2.
MA API 2.1 Customers: (Applicable to both get and delete API)
- For customers who uses content-type/Accept header as 2.1/2.2 in the request - No actions required.
- For customers not using content type/Accept header in the request – Refer the 2.2 response schema in API docs.
MA API 2.2 Customers: (Applicable to both get and delete API)
- For customers who uses content-type/Accept header as 2.2 in the request - No actions required.
- For customers not using content type/Accept header in the request – Refer the 2.2 response schema in API docs.
Sample Response Schema For 2.1 & 2.2 APIs
| 2.0 API Response Schema | 2.1 API Response Schema Customers start using 2.1 Content-Type/Accept headers in the request | 2.2 API Response Schema Not using Content-Type/Accept or Customers start using 2.2 Content-Type/Accept Header in the request |
|---|---|---|
| "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:hid:scim:api:ma:2.0:UserInvitation", "urn:hid:scim:api:ma:2.0:CredentialContainer", "urn:hid:scim:api:ma:2.0:Credential", "urn:hid:scim:api:ma:2.0:PartNumber" "urn:hid:scim:api:ma:2.0:LicenseInfo" "urn:hid:scim:api:ma:2.0:Error"" ] | "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:hid:scim:api:ma:2.1:UserInvitation", "urn:hid:scim:api:ma:2.1:CredentialContainer", "urn:hid:scim:api:ma:2.1:Credential", "urn:hid:scim:api:ma:2.1:LicenseInfo", "urn:hid:scim:api:ma:2.1:User:Photo", "urn:hid:scim:api:ma:2.1:PartNumber", "urn:hid:scim:api:ma:2.1:Error" ] | "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:hid:scim:api:ma:2.2:UserInvitation", "urn:hid:scim:api:ma:2.2:CredentialContainer", "urn:hid:scim:api:ma:2.2:Credential", "urn:hid:scim:api:ma:2.2:LicenseInfo", "urn:hid:scim:api:ma:2.2:User:Photo", "urn:hid:scim:api:ma:2.2:PartNumber", "urn:hid:scim:api:ma:2.2:Error" ] |
[!WARNING]
Failing to adhere the guidelines of API 2.0 shutdown on or before “End of life date” will lead to parsing error in the application if the content type is not specified in request. we always encourage to pass the content type during the implementation.
Upgrade from 2.0 to 2.2
Version 2.1 of the API introduced the Photo ID feature. The changes required to upgrade from version 2.0 to 2.2 are detailed below:
| Type of Change | 2.0 | 2.2 | Scope |
|---|---|---|---|
| Content-Type Header and Accept HTTP headers | application/vnd.assaabloy.ma.credential-management-2.0+json | application/vnd.assaabloy.ma.credential-management-2.2+json | All APIs |
| HTTP POST and PUT Request Body data schema | Schemas: "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:hid:scim:api:ma:2.0:UserAction" ] Example: "urn:hid:scim:api:ma:2.0:UserAction": { "createInvitationCode": "Y", "sendInvitationEmail": "N", "assignCredential": "Y", "partNumber": "MID-SUB-CRD_FTPN_XXXX", "credential": "" } | Schemas: "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:hid:scim:api:ma:2.2:UserAction" ] Example: "urn:hid:scim:api:ma:2.2:UserAction": { "createInvitationCode": "Y", "sendInvitationEmail": "N", "assignCredential": "Y", "partNumber": "MID-SUB-CRD_FTPN_XXXX", "credential": "" } For Search operations, the schema can be ignored in attributes. Example: "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], "attributes": [ "name.givenName", "name.familyName", "emails.value" ] |
|
| Error Schema | urn:hid:scim:api:ma:2.0:Error | urn:hid:scim:api:ma:2.2:Error | Error Responses |
Upgrade from 2.1 to 2.2
Version 2.2 of the API introduced the Custom Mobile ID feature. The changes required to upgrade from version 2.1 to 2.2 are detailed below:
| Type of Change | 2.1 | 2.2 | Scope |
|---|---|---|---|
| Content-Type Header and Accept HTTP headers | application/vnd.assaabloy.ma.credential-management-2.1+json | application/vnd.assaabloy.ma.credential-management-2.2+json | All APIs |
| HTTP POST and PUT Request Body data schema | Schemas: "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:hid:scim:api:ma:2.1:UserAction" ] Example: "urn:hid:scim:api:ma:2.1:UserAction": { "createInvitationCode": "Y", "sendInvitationEmail": "N", "assignCredential": "Y", "partNumber": "MID-SUB-CRD_FTPN_XXXX", "credential": "" } | Schemas: "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:hid:scim:api:ma:2.2:UserAction" ] Example: "urn:hid:scim:api:ma:2.2:UserAction": { "createInvitationCode": "Y", "sendInvitationEmail": "N", "assignCredential": "Y", "partNumber": "MID-SUB-CRD_FTPN_XXXX", "credential": "" } For Search operations, the schema can be ignored in attributes. Example: "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], "attributes": [ "name.givenName", "name.familyName", "emails.value" ] |
|
| Error Schema | urn:hid:scim:api:ma:2.1:Error | urn:hid:scim:api:ma:2.2:Error | Error Responses |