Tenant Portal API Requirements

This topic describes how to obtain a tenant portal API authorization token, and provides the format of the root tenant portal API.

Obtaining Authorization Token Required for All Tenant Portal APIs

Tenant portal APIs use Json Web Tokens (JWT) to secure all endpoints; however, the authentication is accessed from an apiHashSecret that is mapped to each unit.

  1. You can obtain an apiHashSecret for each unit of your property from the response body of a GET call: 
    properties/{propertyGuid}/units
    or 
    properties/{propertyGuid}/units/{unitGuid}
    This is a Cloudpath core API, not a tenant portal API. For more information, refer to Example of Using GET for Units That are Not Part of a Network Segmentation Group. The response output includes a unique apiHashSecret for each unit returned in the response. For example, the apiHashSecret returned for the unit called "Apartment 1" in Example of Using GET for Units That are Not Part of a Network Segmentation Group is: 
    "apiHashSecret": "CPNENCv2:BC|E30EECAF-AEFE-41F5-BBF9-5D3D450155AB|lJCWKjdHjnjH6iwwHS/
V0A==:oXgm2xCUIPuD8yFKYZnNDQ=="
    Therefore, you would use that apiHashSecret to log in to (and get authenticated with) that particular unit only.
  2. Set up the the tenant portal API to log in to the unit:
    1. Create the URI by using the format: 
      https://<Your_Cloudpath_System>/admin/rest/tenant/<API-KEY>/properties/<Property-GUID>/units/login

      Replacing the bold values with actual values, an example API to log in is: 

      https://Jeff245.cloudpath.net/admin/rest/tenant/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/login

      Where:

      • https://Jeff245.cloudpath.net/admin/rest/tenant is the root URI of the Cloudpath system being used (must include https, as shown)
      • yRCjJObWR6ER is an example of an API key generated from the Configuration > API Keys section of the Cloudpath UI
      • Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0 is the GUID of the property that contains the units in question.
      Note: If you change the API key in the Cloudpath UI, all tokens become invalid, and new authentications are required. In addition, if you disable the API key, all API requests are rejected, even if the token is still valid and the user has already been authenticated.
    2. Use a POST call.
    3. In the Request Body, enter your apiHashSecret. An example of the format is: 
      {
"hashedSecret":"CPNENCv2:BC|E30EECAF-AEFE-41F5-BBF9-5D3D450155AB|lJCWKjdHjnjH6iwwHS/
V0A==:oXgm2xCUIPuD8yFKYZnNDQ=="
}
  3. For Request headers, you need only:

    Request Header

    Key Value
    Content-type application/json
  4. Send the request.

    Once the request is sent, you will receive a "Status: 200 OK" if the POST is successful. The response body provides a token. You will need to generate a new token each time the current ones expires. You need to use the active token from this response in the Authorization header on all tenant portal APIs.

    {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBcGFydG1lbnQgMSIsImFjY2Vzc1Rva2VuIjoiWkFZZGxMM0ciLCJwcm9wZXJ0eUd1aWQiOiJQcm9wZXJ0eS1hZmFjY2RmOC01ZTM5LTQxY2UtOTA5OC05NzQ3Y2MzOGFhYTAiLCJ1bml0R3VpZCI6IlVuaXQtZjU5ZjJjOTMtNjc4Ni00ZDhlLWFkYWQtMmU0NGQzM2RmMzk5IiwiYXBpS2V5IjoieVJDakpPYldSNkVSIiwiaWF0IjoxNjE0MTMzNDgwLCJleHAiOjE2MTQxMzM3ODB9.Z-miziYm1c7BK9uW3nWoXC1I4fWd6_uUXQvjUGeVzmg",
    "expireDateTime": "2021-02-24T02:29:40Z",
    "unitGuid": "Unit-f59f2c93-6786-4d8e-adad-2e44d33df399"
}

    When grabbing the token, do not take the quotation marks. In the example above, you would grab the token as follows for using it in the Request Authorization header on a tenant portal API: 

    eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBcGFydG1lbnQgMSIsImFjY2Vzc1Rva2VuIjoiWkFZZGxMM0ciLCJwcm9wZXJ0eUd1aWQiOiJQcm9wZXJ0eS1hZmFjY2RmOC01ZTM5LTQxY2UtOTA5OC05NzQ3Y2MzOGFhYTAiLCJ1bml0R3VpZCI6IlVuaXQtZjU5ZjJjOTMtNjc4Ni00ZDhlLWFkYWQtMmU0NGQzM2RmMzk5IiwiYXBpS2V5IjoieVJDakpPYldSNkVSIiwiaWF0IjoxNjE0MTMzNDgwLCJleHAiOjE2MTQxMzM3ODB9.Z-miziYm1c7BK9uW3nWoXC1I4fWd6_uUXQvjUGeVzmg

Root API

The root for all tenant portal APIs is as follows: 

<Cloudpath FQDN>/admin/rest/tenant/{apiKey}/

Parent topic: Tenant Portal APIs