Multi Tenant Authentication Header

Posted September 20, 2022 by Customer Success ‐ 3 min read

Great new feature! You can now have multiple tenants on the same identity and access manager!

Yonomi Platform now supports multi-tenant authentication from a single Identity and Access Management instance. This new feature makes it easier to configure multiple Yonomi Platform tenants across environments/stages and reduces development effort by allowing the same user accounts to be used across multiple Yonomi Platform tenants.

How it works:

Prior to this update, each Yonomi Platform tenant required a distinct JWT issuer to be configured in order to make authorized calls to the Yonomi API. This update allows for a single JWT issuer to be used against multiple Yonomi Platform tenants.

A new HTTP header has been introduced to support this feature. The purpose of the header is to give developers a way to specify to which tenant an API request is targeted.

Yonomi Platform will expect the new header, x-allegion-installation-reference-id, to be included in API requests, and it will become a requirement for all API calls in the future. This means developers should start adopting modifications to support this feature as soon as possible.

Here’s an example request snippet showing how API calls should specify the new header:

{ "authorization": "Bearer {user-JWT}", "x-allegion-installation-reference-id": "{development-tenant-id}" }

In the example above, the request specifies {development-tenant-id} as the Yonomi Platform tenant targeted for the API call.

Important Note: The first time a JWT is used in a request it will be permanently associated with the target tenant until it expires and cannot be used to make calls to a different Yonomi Platform tenant. A distinct token must be generated for use with each tenant. For example, if a JWT has been used to make calls to a Development tenant, that same JWT cannot be used to make calls to a UAT or Production tenant. Changing the tenant ID in the header while using a JWT that has already been used will result in the original tenant still being the API request target.

Change Impact

With this change, developers are no longer required to configure a unique JWT issuer for each of their Yonomi tenants, making tenant configuration and management an easier task.

As stated above, this is a required change, and Yonomi Platform will expect the new header to be included in all API calls in the future. Developers should start adopting modifications to support this feature before the change becomes a mandatory requirement sometime in 2023.

How to begin using the new feature:

  1. Obtain your tenant IDs. Tenant IDs were provided by Yonomi Customer Success - if you don’t have yours you can reach out to your Yonomi Customer Success engineer to get them.

  2. Begin including the x-allegion-installation-reference-id header in all API calls to Yonomi.

For more information on this feature, check out the User Authentication Configuration section of the Yonomi Platform Tenant Configuration Guide. for details.