Permissions¶

A permission consists of:

Path - API path to allow expressed as a regular expression
Methods - HTTP methods allowed on the path
ACL - Access control list settings

Path¶

Path value can be as simple as .+ meaning any endpoint is acceptable, or more restrictive like /resources/my\.type which means only resource module type my.type is acceptable. A path is matched completely against requested API endpoint and not as a prefix. The client will be allowed to make requests on API endpoint /resources/my.type. It will not be allowed to make API requests on API endpoint like /resources/my.type/58190eb45e12511ab8db56c8. To allow such endpoints, use a path like /resources/my\.type/[0-9a-fA-F]{24}. Expression [0-9a-fA-F]{24} is used to match document ID.

Note

Be sure to escape special characters like . (dot) in a regular expression if necessary.

Methods¶

Methods are HTTP methods GET, POST, UPDATE and DELETE which can be allowed or not on the path. Allowing GET method for a path /resources/my\.type will allow the client to search for a my.type resource. It will not allow creating a new my.type resource since create operation is done via POST method. Allowing UPDATE and DELETE method will not have an effect since there are no operations requiring those methods on the mentioned path. Enabling UPDATE and DELETE makes sense on a path like /resources/my\.type/[0-9a-fA-F]{24}.

ACL¶

ACL or access control list is a list of permissions attached to each document in the system. Jazer provides read, update and delete permission lists for each document. Fetching or updating ACL record can be done by appending .acl to a type on API endpoint path. ACL record of a resource with type my.type and ID 58190eb45e12511ab8db56c8 will be provided on the API endpoint /resources/my.type.acl/58190eb45e12511ab8db56c8.

Example of an ACL record:

{
  "data": {
    "type": "my.type.acl",
    "id": "58190eb45e12511ab8db56c8",
    "attributes": {
      "read": "*",
      "update": [
        {
          "type": "core.user",
          "id": "59bee9ffac610577a9bae5b1"
        },
        {
          "type": "core.user.group",
          "id": "59417170a01c5b0ed21bceab"
        }
      ],
      "delete": [
        {
          "type": "core.user",
          "id": "59bee9ffac610577a9bae5b1"
        }
      ]
    },
    "links": {
      "self": "https://api.jazer.io/resources/my.type.acl/58190eb45e12511ab8db56c8"
    }
  }
}

ACL permission value can be:

* (asterisk) - meaning it is public, anyone is allowed to perform the operation
an array of users and/or user groups

API key with permission containing path /resources/my\.type/[0-9a-fA-F]{24} with enabled DELETE method and ACL turned on will allow deleting resource my.type with ID 58190eb45e12511ab8db56c8 only to the user with ID 59bee9ffac610577a9bae5b1. Turning off ACL on the same API key permission will force the system to ignore ACL record and allow the client to delete any resource of type my.type. The client does not need to authenticate a user when ACL is turned off.

Super ACL record is a special kind of ACL record which contains read and update permission lists for an ACL record. In other words ACL record controls document access, while super ACL record controls ACL record access. Fetching or updating super ACL record can be done by appending .acl.acl to a type on API endpoint path.

Example of an super ACL record:

{
  "data": {
    "type": "my.type.acl.acl",
    "id": "58190eb45e12511ab8db56c8",
    "attributes": {
      "read": [
        {
          "type": "core.user",
          "id": "59bee9ffac610577a9bae5b1"
        }
      ],
      "update": [
        {
          "type": "core.user",
          "id": "59bee9ffac610577a9bae5b1"
        }
      ]
    },
    "links": {
      "self": "https://api.jazer.io/resources/my.type.acl.acl/58190eb45e12511ab8db56c8"
    }
  }
}

The user who has initially created document gets all ACL and super ACL permissions. Other users will not be able to perform any action upon document (if API key undergoes ACL). The document will be hidden from other users. The user can change ACL record to allow other users operations on the document and super ACL record to give administration rights.