Permissions

Permissions are rooted in the /v1/permissions collection.

Each permission is the basic unit to provide a way to limit applications’ access to sensitive information.

Access to resources in the system depends on the access control list set for them. Depending on the access control list, a caller may need to prove its identity by means of an access token passed to the Authorization header (Authorization: Bearer {token}). Please visit Authentication to learn more about how to retrieve an access token.

Authorization notes

When modifying permissions, the caller must have permissions/write permissions on the path /.

When reading permissions, the caller must have permissions/read permissions on the path /.

Minimum permissions

IAM is configured to include minimum permissions, i.e. permissions that cannot be removed, because they are necessary for correct functioning of Nexus.

Currently the following permissions are required:

  • default permissions for acls, with the exception that everyone should be able to see his own permissions

    • acls/read
    • acls/write
  • default permissions for permissions

    • permissions/read
    • permissions/write
  • default permissions for realms

    • realms/read
    • realms/write
  • generic permissions for full read access to the global event log

    • events/read
  • admin specific permissions

    • projects/read
    • projects/write
    • projects/create
    • organizations/read
    • organizations/write
    • organizations/create
  • KG specific permissions

    • resources/read
    • resources/write
    • resolvers/write
    • views/query
    • views/write
    • schemas/write
    • files/write

Replace permissions

This operation overrides the collection of permissions.

PUT /v1/permissions?rev={previous_rev}
  {...}

…where {previous_rev} is the last known revision number for the permissions. If there are only minimum permissions present present, this query parameter can be omitted.

The json payload contains the set of permissions to be added.

Example

Request
curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/permissions?rev=1" -d \
'{
  "permissions": [
    "newpermission/read",
    "newpermission/write"
  ]
}'
Full source at GitHub
Payload
{
  "permissions": [
    "newpermission/read",
    "newpermission/write"
  ]
}
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/permissions",
  "@type": "Permissions",
  "_rev": 2,
  "_createdAt": "2019-01-22T13:15:54.667Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T13:22:03.007Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Subtract permissions

This operation removes the provided permissions from the existing collection of permissions.

PATCH /v1/permissions?rev={previous_rev}
  {...}

…where {previous_rev} is the last known revision number for the permissions.

The json payload contains the set of permissions to be deleted. Example

Request
curl -XPATCH -H "Content-Type: application/json" "https://nexus.example.com/v1/permissions?rev=2" -d \
'{
  "@type": "Subtract",
  "permissions": [
    "newpermission/write"
  ]
}'
Full source at GitHub
Payload
{
  "@type": "Subtract",
  "permissions": [
    "newpermission/write"
  ]
}
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/permissions",
  "@type": "Permissions",
  "_rev": 1,
  "_createdAt": "2019-01-22T13:15:54.667Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T13:22:03.007Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Append permissions

This operation appends the provided permissions to the existing collection of permissions.

PATCH /v1/permissions?rev={previous_rev}
  {...}

…where {previous_rev} is the last known revision number for the permissions.

The json payload contains the set of permissions to be added.

Example

Request
curl -XPATCH -H "Content-Type: application/json" "https://nexus.example.com/v1/permissions?rev=3" -d \
'{
  "@type": "Append",
  "permissions": [
    "newpermission/create"
  ]
}'
Full source at GitHub
Payload
{
  "@type": "Append",
  "permissions": [
    "newpermission/create"
  ]
}
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/permissions",
  "@type": "Permissions",
  "_rev": 2,
  "_createdAt": "2019-01-22T13:15:54.667Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T13:22:03.007Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Delete all permissions

This operation deletes the all the user defined permission and resets the collection to minimum permissions.

DELETE /v1/permissions?rev={previous_rev}

…where {previous_rev} is the last known revision number for the permissions.

Request
curl -XDELETE "https://nexus.example.com/v1/permissions?rev=4"
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/permissions",
  "@type": "Permissions",
  "_rev": 3,
  "_createdAt": "2019-01-22T13:15:54.667Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T13:22:03.007Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Fetch permissions (latest revision)

GET /v1/permissions
Request
curl "https://nexus.example.com/v1/permissions"
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/permissions",
  "@type": "Permissions",
  "permissions": [
    "acls/read",
    "acls/write",
    "events/read",
    "files/write",
    "organizations/create",
    "organizations/read",
    "organizations/write",
    "permissions/read",
    "permissions/write",
    "projects/create",
    "projects/read",
    "projects/write",
    "realms/read",
    "realms/write",
    "resolvers/write",
    "resources/read",
    "resources/write",
    "schemas/write",
    "views/query",
    "views/write"
  ],
  "_rev": 10,
  "_createdAt": "2019-01-22T13:15:54.667Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T13:22:03.007Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Fetch permissions (specific revision)

GET /v1/permissions?rev={rev}

…where {rev} is the revision number of the permissions to be retrieved.

Request
curl "https://nexus.example.com/v1/permissions?rev=1"
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/permissions",
  "@type": "Permissions",
  "permissions": [
    "acls/read",
    "acls/write",
    "events/read",
    "files/write",
    "organizations/create",
    "organizations/read",
    "organizations/write",
    "permissions/read",
    "permissions/write",
    "projects/create",
    "projects/read",
    "projects/write",
    "realms/read",
    "realms/write",
    "resolvers/write",
    "resources/read",
    "resources/write",
    "schemas/write",
    "views/query",
    "views/write"
  ],
  "_rev": 3,
  "_createdAt": "2019-01-22T13:15:54.667Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T13:22:03.007Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub