Tenant Configuration Guide

When you’re ready to get started building solutions with Yonomi you’ll need to request and configure your Yonomi Platform Tenant. This guide will walk you through the steps to get you up and running.

📘 What is a Tenant?

Yonomi provides customers with one or more tenants to build and run their solutions. A tenant is a dedicated instance of Yonomi Platform software services. A customer will typically use at least two tenants - one for each of their development and production environments - and may request as many as needed to build their solutions. Tenants can be thought of as synonymous with a development environment/stage, and a customer may run multiple solutions on a single production tenant. Users, devices and other objects are created and stored in a tenant.

Tenants are logically distinct. For example, users and devices created on a customer’s development tenant are distinct from users and devices created on a customer’s production tenant. This is the case even when using the same Identity and Access Management System (IAM) across Yonomi tenants; a user on a production tenant with ID jane.user@yourcompany.com is distinct from a user on the development tenant of the same identity according to the IAM. Likewise, tenants are unique across customers and data is not shared or accessible across different customer tenants.

Each tenant provided by Yonomi must be configured before it can be used.

There are 3 steps to tenant configuration:

• User Authentication Configuration
• Callback URL Configuration
• Webhook Setup & Configuration

One additional, optional configuration step is Custom Vendor API Key Management, covered at the end of this guide.

User Authentication Configuration

The first and most important step in configuring your Yonomi tenant is to establish a user authentication source and begin generating JSON Web Tokens (JWTs) that Yonomi can use to identify and authorize your users. Yonomi relies on your existing OAuth2.0-compliant Identity & Access Management (IAM) solution to authorize requests made to your Yonomi Platform tenants on behalf of your users. In other words, Yonomi uses the very same user access and authorization systems you already use today. This means you won’t need to create and manage separate users in Yonomi - your existing users simply interact with Yonomi. The Yonomi Platform verifies your user requests by validating user tokens against your IAM public key for every request. This identity management flow allows for a seamless user experience between the Yonomi platform, 3rd Party devices and your applications.

You can use a single Identity & Access Management instance across multiple Yonomi Platform tenants. Yonomi will look for a special header in all HTTP requests to determine which tenant the request is targeting. This HTTP header is required and must be sent with all requests regardless of the number of Yonomi Platform tenants you use. Details on this header are covered further down in this guide.

For an explanation of how Yonomi supports authorization for your users, see User Access and Authorization.

This step requires that you have the ability to generate OAuth2.0-compliant JSON Web Tokens, or JWTs. If you already use a popular IAM solution today for user management such as Auth0, Okta, PingIdentity or AWS Cognito then you’re in a great position to be able to generate JWTs that can be used with Yonomi to authenticate and authorize your users. If not, a good first step will be to identify the right IAM for your needs. If you need help here you can reach out to us for guidance.

JWTs generated by your IAM must meet to the following requirements:

• must conform to the OpenID Connect standard
• must be be signed by your private key
• must include kid claim in the payload header
• must include sub, iss and exp claims in the payload body
• sub claim must be unique per user
• exp claim must specify a time in the future when the token expires
• iss claim must be a URI that can be used to resolve your IAM’s OpenID Configuration at the standard-specified path: [iss]/.well-known/openid-configuration
• JSON Web Keyset (JWKS) URI with public key must be accessible from the jwks_uri attribute in the Open ID Configuration
• JWKS must have an n RSA modulus - Yonomi only accepts RS256 encrypted JWTs

You can use the jwt.io site to decrypt and view your token for validity.

Once you are able to generate JWTs that conform to this standard, contact your Yonomi Customer Support engineer (or Yonomi PreSales) and provide an unexpired sample JWT, which will be used to configure your tenant.

Making Authenticated Calls to your Yonomi Tenant#

After your tenant is configured, you’ll need to set two HTTP headers for any request sent to Yonomi in order for the request to be authorized:

• The Authorization HTTP header should be set to the value of the user’s JWT to execute authenticated queries, structured as: Authorization: Bearer: jwt-token where jwt-token is a valid, unexpired user JWT.

• A x-allegion-installation-reference-id header must also be included in your HTTP requests to tell Yonomi Platform which tenant the request is targeting. You’ll structure the header as: x-allegion-installation-reference-id: tenant-id where tenant-id is global unique identifier (GUID) of the tenant you want to target. You should have received the Tenant ID for each of your tenants when they were initially set up - if you don’t have yours just reach out to your Yonomi Customer Success resource to obtain the tenant ID for each of your environments.

With the Authorization and x-allegion-installation-reference-id HTTP headers set, you’re now ready to begin making GraphQL queries in your own environment. Here’s an example CURL you can as a test request:

curl 'https://platform.yonomi.cloud/graphql' -H 'Content-Type: application/json' -H 'Authorization: Bearer a.sample.jwt' -H 'x-allegion-installation-reference-id: tenant-id' --data-binary '{"query":"query basicInfo { tenant { id displayName } }"}'

🚧 What do I do if responses to requests return as “Unauthorized”?

If you find that your calls are returning as unauthorized when you attempt to run them, try replacing the token in the Authorization header with a newly generated, unexpired JWT. If you are still experiencing Unauthorized requests, confirm the tenant ID value specified in the x-allegion-installation-reference-id header matches the tenant configured by Yonomi as associated with your Identity and Access Management system.

Callback URL Configuration

The second step in configuring your tenant is to set your device authorization callback URLs. Yonomi allows you to access and control devices after they have been authorized by the device vendor’s authorization process. This process is called Account Linking, and involves directing a user to a vendor-provided URL in order to enter the username and password credentials for the account that owns the device. As an example, in order to use a Schlage lock you’ll need to load an account linking URL and provide the Schlage credentials used to provision the lock when it was first installed. Once authorized, any devices associated with the newly linked account will be available for use through Yonomi.

📘 What if I don’t set my callback URLs?

If you don’t set your callback URLs your user’s experience will terminate at a very simply “Success” or “Failed” page upon completion of the Account Linking process

Key to the account linking process is a redirect of the user to the vendor’s account linking URL. Once the linking process is complete, Yonomi allows you to redirect the user back to your app with a callback URL. Callback URLs allow you to send the user back to your app experience in a seamless way to continue the flow after an account has been linked and devices are accessible. Yonomi allows you to set two callback URLs - one for successful linking (Success Callback URL) and one for a failed linking process (Failure Callback URL) which can result for instance during attempts to use invalid vendor login credentials.

🚧 Callback URLs are static; they cannot be customized per user or include dynamic query string parameters.

To configure your callbacks, just send the URLs to your Yonomi Customer Support engineer (or Yonomi PreSales). They’ll let you know once they’ve been configured.

To test your callback URLs, simply complete the account linking process with a user account and make sure you see the appropriate URL redirect after the process is complete.

Webhook Setup & Configuration

The last step in tenant configuration is to begin processing webhook events from Yonomi Platform. Webhooks - also known as user-defined HTTP callbacks - are automated, one-way messages sent from a service to a client when an event occurs. Webhooks are a scalable, efficient and convenient way for applications to receive real-time information of the events monitored or managed by that service. Yonomi uses webhooks to asynchronously provide data about device state changes to your applications.

📘 For a full list of all event types supported by the Yonomi platform visit the Yonomi Webhooks reference.

Because webhooks are useful once you have begun working with devices, webhook setup is covered in the separate Getting Started with Webhooks Guide. You can follow that guide to get webhooks configured and complete your Yonomi Platform tenant configuration

Congratulations! You’ve successfully completed configuration of your Yonomi Tenant.

Optional: Custom Vendor API Key Management#

Yonomi uses our own API keys to make calls against vendor clouds in order to interact with devices. This approach makes sense for most customers, however if you have your own API keys with a particular vendor and/or need to establish a more direct relationship with that, Yonomi can configure your tenant to use your own API keys when making calls to a given vendor cloud. Please contact Yonomi Customer Care if you’re interested in making this change.