Introduction

...

The Authorisations API can be used to manage entity relations regarding to different types of permissions granted to a subject by an object.

The Authorisation records can be managed via the Management API. The Management API support basic CRUD operations for each of the items.For all three item types, the requested JSON objects can be filtered by issuing a "filter" query parameter along with the HTTP GET request.
The filter string uses the SCIM filtering syntax specified in RFC 7644. The available filterable criteria will be given for each of the entity types in question along with examples of filter usage.

Up-to-date API description can always be found in the onePortal instance's /apidoc endpoint. The reader is advised to take a look at the documentation. Also note that in the example code listings below, the variables "client_id", "client_secret" and "host" have to be changed to reflect your own setup.

Managing Authorisations

The Authotisations can be managed via the authorisation REST API endpoint. The API contains methods for viewing authorisations, creating new authorisations as well as modifying and removing existing authorisations.

Fetching Authorisations

The Authorisations can be retrieved by issuing an HTTP GET request to the "authorisation" endpoint of the Management API. There are two different endpoints, one of which can be used to retrieve multiple JSON objects and another, which can be used to retrieve a single entity by issuing an id. Both of these operations require the AUTHORISATION_VIEW permission.

The Authorisations can be filtered by issuing a filter string parameter as an HTTP GET query parameter. The Authorisations can be filtered by Authorisation Type, Authorisation Source, subject value, object value and the code of the namespace owning the authorisation. The filterable parameters are "object.value", "subject.value", "auhtSource", "authType" and "nsCode". view and manage Authorisation objects.

The complete up-to-date API documentation is accessible from the Management API documentation. This article describes some of the basic features with examples.

Creating an Authorisation

A new Authorisation can be created by a client or an user with the required permission to create Authorisations.

In this example an Authorisation to file for permit is created between two Users.

curl -X 'POST' \
  'https://id.example.com/api/rest/v1/authorisation' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "file_for_permit",
  "validFrom": "2022-05-23T13:03:21.711Z",
  "validTo": "2022-06-23T13:03:21.711Z",
  "nsCode": "root",
  "subject": {
    "type": "User",
    "value": "58cfb7353874e103fc81ec5f"
  },
  "object": {
    "type": "User",
    "value": "5a325c543874e16a85710c5e"
  }
}'

Response to successful request includes all details about the new Authorisation:

import requests

client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint = "/api/rest/v1/authorisation"
url = host + endpoint

# look only for items that are owned by the organisation with code "root"
params = {"filter": "nsCode eq \"root\"" }

response = requests.get(url, params = params, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

...

{
  "id": "628b875329795876273eb847",
  "type": "file_for_permit",
  "validFrom": "2022-05-23T13:03:21.711Z",
  "validTo": "2022-06-23T13:03:21.711Z",
  "revoked": false,
  "meta": {
    "created": "2022-05-23T13:08:35.680093Z",
    "lastModified": "2022-05-23T13:08:35.680093Z"
  },
  "nsCode": "root",
  "creator": {
    "type": "ManagementApiClient",
    "id": "1248769513590337"
  },
  "subject": {
    "type": "User",
    "value": "58cfb7353874e103fc81ec5f"
  },
  "object": {
    "type": "User",
    "value": "5a325c543874e16a85710c5e"
  },
  "effectiveValidTo": "2022-06-23T13:03:21.711Z",
  "active": true
}

Listing Authorisations delegated to an User

In this example we list the active Authorisations which have been delegated to a specific User.

curl -X 'POST' \
  'https://fiid.trivoreidexample.com"
endpoint = "/api/rest/v1/user/58cfb7353874e103fc81ec5f/authorisation/"subject' \
 # the id of the authorisation to be fetched
authz_id = "12345" 
url = host + endpoint + authz_id

response = requests.get(url, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Creating an Authorisation

To create an Authorisation, issue an HTTP POST request to the "authorisation" endpoint. The endpoint requires the client to have the AUTHORISATION_CREATE permission.

As for the parameters, the namespace code is optional, and if omitted, the Authorisation object will be created to the default namespace of the management API client. If the Authorisation should be created in some other namespace, then the nsCode parameter is required and must be the code of one of the namespaces accessible to the API client. A valid Authorisation Type is required as well as subject and an object.

Additionally, Authorizations can optionally be assigned validity time by issuing validFrom and validTo parameters. The value of these parameters should be a ISO 8061 formatted datetime. The endpoint will return code 400, if the given values cannot be parsed. The example code listing below shows how to create an Authorisation with a string object and subject. The type of the Authorisation is "employment".

-H 'accept: application/json' \
  -H 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
  -H 'Content-Type: application/json' \
  -d '{
  "active": true
}'

The response includes the Authorisation we just created.

{
  "totalResults": 1,
  "startIndex": 0,
  "itemsPerPage": 20,
  "resources": [
    {
      "id": "628b875329795876273eb847",
      "type": "file_for_permit",
      "validFrom": "2022-05-23T13:03:21.711Z",
      "validTo": "2022-06-23T13:03:21.711Z",
      "revoked": false,
      "meta": {
        "created": "2022-05-23T13:08:35.680Z",
        "lastModified": "2022-05-23T13:08:35.680Z"
      },
      "nsCode": "root",
      "creator": {
        "type": "StringManagementApiClient",
        "valueid": "value11248769513590337"
      },
      "subject": {
        "type": "StringUser",
        "value": "value258cfb7353874e103fc81ec5f"
      },
      "validFromobject": "2018-10-25T12:00:31Z"{
        "type": "User",
        "value": "5a325c543874e16a85710c5e"
      },
      "validToeffectiveValidTo": "20192022-1006-25T1223T13:0003:31Z21.711Z",
}   response = requests.post(url = url, json = payload, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Removing an Authorisation

...

 "active": true
    }
  ]
}

Revoking an Authorisation

In this example we revoke the Authorisation which was created previously. We also give a reason for the revocation.

curl -X 'POST' \
  'https://id.example.com/api/rest/v1/authorisation/628b875329795876273eb847/revoke' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
  -H 'Content-Type: application/json' \
  -d '{
  "cause": "Unnecessary"
}'

The response includes all details of the now revoked Authorisation. The changed parameters include revoked, revokedAt, revocationDetails, active.

import{
requests  client_"id =": "628b875329795876273eb847",
  "0880905547415718type": client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint = "/api/rest/v1/authorisation/"

# the id of the authorisation to be fetched
authz_id = "12345"
url = host + endpoint + authz_id

response = requests.delete(url, auth = (client_id, client_secret))

print(response.status_code)"file_for_permit",
  "validFrom": "2022-05-23T13:03:21.711Z",
  "validTo": "2022-06-23T13:03:21.711Z",
  "revoked": true,
  "revokedAt": "2022-05-23T13:20:34.219Z",
  "revocationDetails": {
    "cause": "Unnecessary"
  },
  "meta": {
    "created": "2022-05-23T13:08:35.680Z",
    "lastModified": "2022-05-23T13:08:35.680Z"
  },
  "nsCode": "root",
  "creator": {
    "type": "ManagementApiClient",
    "id": "1248769513590337"
  },
  "subject": {
    "type": "User",
    "value": "58cfb7353874e103fc81ec5f"
  },
  "object": {
    "type": "User",
    "value": "5a325c543874e16a85710c5e"
  },
  "effectiveValidTo": "2022-06-23T13:03:21.711Z",
  "active": false
}