Simple usage examples

The Management API endpoint details can always be found in the onePortal instance’s /apidoc endpoint, for example at https://fi.trivoreid.com/apidoc. The API doc is automatically generated by Swagger and will always show the current list of available endpoints.

As the API is subject to change, the details of the management API endpoints will not be listed in this document. Instead, please refer to the documentation at the /apidoc endpoint. Each of the API commands will list the permissions required to access it.

Almost all of the Management API endpoints require authentication via the HTTP ‘Basic’ authentication scheme. The request library for Python handles the authentication as shown in the examples later. When accessing the API with curl, the Basic authentication header is inserted in the request with the -H switch like follows

curl -X GET "https://fi.trivoreid.com/api/rest/v1/user" \
    -H "accept: application/json" \
    -H "authorization: Basic m9vOmJhcg=="

Note that the user name and password are given in form username:password and then encoded as base64. See RFC 7617 for more info. Also, make sure to include the ‘accept’ header like in the example above as it is required by some of the API endpoints.

Especially in case of any errors, make sure to always pay attention to the response headers and content as they contain information about any errors that may occur. For example, if the client does not have the required permissions to access a certain resource, onePortal will reply with status code 403 along with the name of the permission required for resource access. Such a response will read like follows.

{
    "errorMessage": "Client does not have required permission ACCOUNT_VIEW.",
    "statusCode": 403
}