Authorisations API Usage Examples

The Authorisations API can be used to view and manage Authorisation objects.

The complete, up-to-date API documentation is accessible from the Management API documentation. This page walks through some of the basic features with examples.

Creating an Authorisation

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

In this example, an Authorisation to file for a permit is created between two Users — a subject (delegate) authorised to act, and an object (principal) on whose behalf the subject may act:

POST /api/rest/v1/authorisation
Content-Type: application/json

{
  "type": "file_for_permit",
  "subject": {
    "type": "User",
    "value": "5c3dc19ade95082b300d2b41"
  },
  "object": {
    "type": "User",
    "value": "5c3dc19ade95082b300d2b4a"
  },
  "validFrom": "2022-05-24T10:49:36.271Z",
  "validTo": "2023-05-24T10:49:36.271Z"
}

The response to a successful request includes all details about the new Authorisation, including its generated id and creator:

{
  "id": "5c3dc19ade95082b300d2b4a",
  "type": "file_for_permit",
  "subject": {
    "type": "User",
    "value": "5c3dc19ade95082b300d2b41"
  },
  "object": {
    "type": "User",
    "value": "5c3dc19ade95082b300d2b4a"
  },
  "nsCode": "customers",
  "creator": {
    "type": "User",
    "id": "5c3dc19ade95082b300d2b41"
  },
  "validFrom": "2022-05-24T10:49:36.271Z",
  "validTo": "2023-05-24T10:49:36.271Z",
  "active": true,
  "revoked": false
}

Listing Authorisations delegated to a User

This example lists the active Authorisations that have been delegated to a specific User, by filtering on subject.value and revoked:

GET /api/rest/v1/authorisation?filter=subject.value eq "5c3dc19ade95082b300d2b41" AND revoked ne true

The response includes the Authorisation created above, among any others matching the filter.

Revoking an Authorisation

This example revokes the Authorisation created above, giving a reason for the revocation:

POST /api/rest/v1/authorisation/5c3dc19ade95082b300d2b4a/revoke
Content-Type: application/json

{
  "cause": "Permit application withdrawn"
}

The response includes all details of the now-revoked Authorisation. The changed fields are revoked, revokedAt, revocationDetails, and active:

{
  "id": "5c3dc19ade95082b300d2b4a",
  "type": "file_for_permit",
  "subject": {
    "type": "User",
    "value": "5c3dc19ade95082b300d2b41"
  },
  "object": {
    "type": "User",
    "value": "5c3dc19ade95082b300d2b4a"
  },
  "nsCode": "customers",
  "creator": {
    "type": "User",
    "id": "5c3dc19ade95082b300d2b41"
  },
  "validFrom": "2022-05-24T10:49:36.271Z",
  "validTo": "2023-05-24T10:49:36.271Z",
  "active": false,
  "revoked": true,
  "revokedAt": "2022-06-01T08:12:03.000Z",
  "revocationDetails": {
    "cause": "Permit application withdrawn"
  }
}