Skip to main content

TenX Application Integration Workflow

Paul Schneider
  • Updated

Overview

The Prism API supports development of Tenant Experience (TenX) applications, which will act-on- behalf of a given user. This allows a privileged user to request a short-term, maximum one hour token which can be used to make requests for a given tenant user.

 

Prerequisites / Permissions

To support this end, the PMO must grant a TenX application credentials to a management-based account, often with a pseudo-email address, and the account must have permissions. It is recommended that a special permission group be created for this purpose including the permissions:

  • API / Allow a user to authenticate as a Tenant Experience (TenX) application
  • Companies / Can View all Companies

Support only allows this to work for tenant users and only those tenant users in a single, Prism account.

 

API Request / API Key

This request is only valid in the presence of an authorized, Prism API Key. Your BE Solutions Engineer will provide this to you in a secure link, separately from this document.

 

Request

POST https://api.connect.buildingengines.com/auth/txtoken
Accept: application/json;version=1
Content-Type: application/json
X-Prism-App: "<your API Key here>"

 

Body

{
"tenant_email": "<Email address of tenant to get token for>", 
"tenant_account_id: "<GUID of Prism Account ID for tenant>" 
}

All fields are required.

 

Response Codes

  • 403 - Not permitted
  • 404 - User not found or not in scope
  • 200-OK

Response Body

{
"token": "<JWT Bearer Token for use in API calls for the tenant>", 
"api_key_prefix": "<Prefix portion of the callers API Key>",
"id": "<GUID of the target tenant User ID in Prism>", 
"impersonation_email": "<Email of the target tenant User in Prism>" 
}

The given token should be used in the Authorization header, prefixed by Bearer as is normal in Prism API calls. The token will last no more than one hour after which, if needed, it should be reacquired via this API.

 

Prism UI Setup

We’ve added a TX App option within PMO admin permissions. A PMO will have the ability to grant this permission to TenX applications, such as HqO.

A PMO or API Solutions Engineer should create a custom user group that we will assign TenX app users to. Once that group are assigned to the TX App permission, users within that custom group will be able to act-on-behalf of a given user through the API details provided above, along with your API Key.

Here’s what the setup looks like in Prism:

  • Navigate to admin permissions
    • Admin > Manage Permissions

447b49d4-dc6d-4a85-98eb-61081655982f.png

  • Create new permission group

    • Admin > Manage Permissions > click Create Group button in top right

      The TenX App permission will allow a PMO to create and designate a custom user permission group within the Management Organization (ie. ‘TenX App User’).

      Note: The TX App permission is only available for Management Organization users, not Tenant or Vendor users, so we need to make sure to select Management Organization.

3b35e26c-a5bf-431a-a79a-fc3f6de9b066.png

  • Assign TX App and Companies permission to Ten X group

    • Admin > Manage Permissions > TX App

a7802456-32b1-4f35-bd50-785cfe35f11b.png

    • Admin > Manage Permissions > Companies

a65e9357-c1b9-43c2-8d54-74bdb18a3792.png

  • PMO should grant a TenX application credentials to a management-based account, often with a pseudo-email address

    • My Users > click blue Add User button in top right

c4f6989b-db91-46c9-bab1-82a57f2e6ae9.png

a5aef1a8-f9c7-46a5-a01b-74b6b4a79d34.png

  • Assign permissions to user
    My Users > All Users > filter by the TenX user you need to update the permissions for > click Permissions

da1f1d60-582a-47e3-836e-37a4528e41ab.png

 

Login Redirection Link

The TenX endpoint allows for an additional, single-sign on functionality. In this case, you wish to get a URL to redirect the user to or open in a new window, that will login appropriately. This does not support deep linking – the user will be authenticated and sent to the dashboard. For limited interactions where the App simply wants to redirect the user to Prism, without having to login again, is satisfied by this.

To use this, you add a parameter in the txtoken payload:

"login_link": true

Assuming the login is successful, the resulting payload will continue to include a token for use directly by the TenX application but, in addition, will return a data element login_url which will be a fully-formed link to login to Prism Web UI similar to https://prism-apac.buildingengines.com/login?tac=sajjgr9qbhdka. This login code will expire in 1 minute or on it’s first usage so the intent is for an immediate redirection.

 

 

 

Powered by Zendesk