Access Control API

The Access Control API provides access to manage units and tenants for an account.

API Routes and Documentation

The Access Control service name is “accesscontrol”, which can be substituted into the route prefix format of the selected environment (e.g. https://accesscontrol.insomniaccia.com ). The Swagger documentation can be found by appending “/swagger” to the route prefix (e.g. https://accesscontrol.insomniaccia.com/swagger ). To the view the appropriate documentation, select “v2.0” from the drop-down. The v1.0 API exists for legacy support only and is subject to deprecation in the future. The v3.0 API is not yet available for Property Management Systems. Like all OpenTech IoE APIs, service routes are available for checking the availability and health of the service. Calling the API

Every authorized request to the API requires an “Authorization” and an “api-version” header. The authorization header indicates to the API that you are using bearer token authentication using your JWT access token acquired from the Authorization API. The “api-version” header should contain a static value of “2.0” to call the correct routes.

API calls will return one of the following responses:

• 200 OK – Your request was successful, and the response body will contain additional data.
• 400 Bad Request – Your request has invalid data, and the response body will give reasons for the invalid response.
• 401 Unauthorized – Your authorization token is expired.
• 403 Forbidden – You tried to access a resource or operation that is not available to your credentials.
• 404 Not Found – You tried to access a resource that does not exist or is not visible with your credentials.
• 5XX – The server has encountered an internal error or network timeout and you should retry your request.

Timeout, Back-off and Retry

Occasionally, the API will generate a 500-level error due to unforeseen circumstances in the infrastructure. When this occurs, it is helpful to have implemented a back-off and retry strategy. Specifically, when an error is encountered, you should wait a brief period of time (back-off) and then reissue your original call (retry). If you encounter an error again, extend your waiting period before retrying. Repeat this process, increasing the waiting period until your call succeeds or you reach a preset limit of calls, at which point you should consider logging your failed request and contacting STC Administrators. When you receive a successful response, you can resume your normal strategy until the next error is encountered.