Authentication and Authorization

All HID Origo API endpoints require authentication using an OAuth 2.0 Bearer Token (access_token). Every request to the API must include a valid token in an Authorization HTTP header with the following format:

Authorization: Bearer {access_token}

These tokens are generated on behalf of "System Accounts", which are created an managed using the HID Origo Management Portal, using the "Organization Administration" view which is available to holders of the "Organization Administrator" role. Detailed instructions on creating and managing System Accounts is outside the scope of this document.

Identity Provider Information

The following table provides a summary of the Identity Provider properties:

Password-Based Authentication

The following sample request and response demonstrates generating a Bearer Token using the client_credentials grant type. Any line breaks are added for readability only.

POST /authentication/customer/{organization_id}/token HTTP/1.1
Host: api.origo.hidglobal.com
Content-Type: application/x-www-form-urlencoded

client_id=12345-OSRV123456789
&client_secret=K5bkps7mtnq7VDQr
&grant_type=client_credentials

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "access_token": "78HOfQBBBXI3C22rm35DaTrjnKnTpz3WnSJ+INqE",
    "id_token": "eyJraWQiOiIx...78Q",
    "token_type": "Bearer",
    "expires_in": 3600
}

Origo Identity Positioning Password-Based Authentication

The following sample request and response demonstrates generating a Bearer Token using the client_credentials grant type. Any line breaks are added for readability only.

POST /authentication/customer/{organization_id}/token HTTP/1.1
Host: api.prod.oip.origo.hidglobal.com
Content-Type: application/x-www-form-urlencoded
X-Request-ID: {organization_id}

client_id=12345-OSRV123456789
&client_secret=K5bkps7mtnq7VDQr
&grant_type=client_credentials

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "access_token": "78HOfQBBBXI3C22rm35DaTrjnKnTpz3WnSJ+INqE",
    "id_token": "eyJraWQiOiIx...78Q",
    "token_type": "Bearer",
    "expires_in": 3600
}

Certificate-Based Authentication

Certificate-based authentication is supported through the use of JSON Web Tokens (JWT).

Pre-requisites

The System Account identifier and a token URL are used as input to the signed token. The following instructions provide guidance on how to configure a System Account for PKI authentication and to capture the properties to be included in the token.

1. Create (or edit) a System Account and assign the appropriate role(s).
2. In the PKI certificate section, upload the PKI certificate (public key):
3. Save the settings to return to the Organization Administration screen.
4. In the System Accounts section, obtain the Client ID and Token URL:

Generating a Signed JWT

With the System Account created and a PKI certificate uploaded, a JWT can be created and signed. The token needs to include certain claims:

Below is a sample payload using the values from previous examples. This should be signed using the private key to produce a valid JWT:

{
    "sub": "1234-OSRV123456789",
    "iss": "1234-OSRV123456789",
    "aud": "https://auth-us.api.hidglobal.com/idp/1234567890abcdefgh/authn/token",
    "nbf": "1597219200", // 2020-08-12 08:00 UTC
    "exp": "1597222800", // 2020-08-12 09:00 UTC
    "jti": "06aa8891-5ea9-4425-8840-52f657fe768b",
    "iat": "1597219200", // 2020-08-12 08:00 UTC
}

This payload is then signed using the private key and converted to a Base64 encoded string which can be used in API requests. Additional guidance and sample applications in multiple languages are available as part of the HID Global Authentication Service Documentation.

POST /authentication/customer/{organization_id}/token HTTP/1.1
Host: api.origo.hidglobal.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion=ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5SnpkV0lpT2lJeE1qTTBMVTlUVWxZeE1qTTBOVFkzT0RraUxDSnBjM01pT2lJeE1qTTBMVTlUVWxZeE1qTTBOVFkzT0RraUxDSmhkV1FpT2lKb2RIUndjem92TDJGMWRHZ3RkWE11WVhCcExtaHBaR2RzYjJKaGJDNWpiMjB2YVdSd0x6RXlNelExTmpjNE9UQmhZbU5rWldabmFDOWhkWFJvYmk5MGIydGxiaUlzSW01aVppSTZJakUxT1RjeU1Ua3lNREFpTENKbGVIQWlPaUl4TlRrM01qSXlPREF3SWl3aWFuUnBJam9pTURaaFlUZzRPVEV0TldWaE9TMDBOREkxTFRnNE5EQXROVEptTmpVM1ptVTNOamhpSWl3aWFXRjBJam9pTVRVNU56SXhPVEl3TUNKOS5IY05tdmRjbEZsX2VzeG9aZXo1M0prVTlURWNSZGFsZ2NxYmUwWEJwR3pz

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "access_token": "78HOfQBBBXI3C22rm35DaTrjnKnTpz3WnSJ+INqE",
    "id_token": "eyJraWQiOiIx...78Q",
    "token_type": "Bearer",
    "expires_in": 3600
}

Authentication Expiration Policy for System Accounts

It is recommended to monitor token expiration timelines and update them as required to prevent any disruptions.

PKI Based Authentication:

• Certificates uploaded for system accounts during PKI-based authentication, the default expiration period is one year.
• If the certificate expires and stops functioning, re-upload the certificate to restore functionality and ensure uninterrupted operation.

Password Based Authentication:

• For system accounts enabled with password-based authentication, the default expiration period is five years.

Token Expiry

All tokens have an expiry threshold and a session timeout. The expires_in property will include the maximum lifetime of the token in seconds, which is currently 3600 but is subject to change. Developers are encouraged to make this value configurable or dynamically read it from the token. Attempting to use an expired token will result in a HTTP 401 Unauthorized response. Any application consuming HID Origo APIs must support requesting a new token on expiry.

Application Identifiers

In addition to a System Account and associated credentials, an Application Identifier and version must be provided with each request using custom HTTP headers:

• Application-ID
• Application-Version

The Application Identifier is provided and approved for use in production once the application has been certified through the Technology Partner Service program.

A sample request including the Application-ID and Application-Version headers is provided below:

GET /credential-management/customer/{organization_id}/users
Host: ma.api.assaabloy.com
Authorization: Bearer 78HOfQBBBXI3C22rm35DaTrjnKnTpz3WnSJ+INqE
Content-Type: application/vnd.assaabloy.ma.credential-management-2.2+json
Application-ID: HID-Sample-Application
Application-Version: 2.3

Data Security

HID Origo supports TLS version 1.2 and above, to ensure the security and privacy stays ahead of potential vulnerabilities and to meet regulatory requirements.