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".

To fetch the contents of a single Authorisation, simply append the internal id of the Authorisation to the request URL. The example below demonstrates this practice.

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".

Removing an Authorisation

Authorisations can be removed by issuing an HTTP DELETE request to the "authorisation/{id}" endpoint. The endpoint requires the client to have the AUTHORISATION_REMOVE permission and the Authorisation must exist in one of the accessible namespaces. The code listing example below shows how to remove an existing Authorisation. The Authorisation is marked as deleted but is still available for auditing.