Outdated version

You are browsing the docs for Nexus v1.8.x, the latest release is available here

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.

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

Please visit Authentication & authorization section to learn more about it.

Minimum permissions

Delta 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 event log through Server Sent Events

    • events/read

  • default permissions for organizations

    • organizations/read
    • organizations/write
    • organizations/create

  • default permissions for projects

    • projects/read
    • projects/write
    • projects/create

  • default permissions for resources

    • resources/read
    • resources/write

  • default permissions for resolvers

    • resolvers/write

  • default permissions for views

    • views/query
    • views/write

  • default permissions for schemas

    • schemas/write

  • default permissions for files

    • files/write

  • default permissions for storages

    • storages/write

  • default permissions for archives

    • archives/write

  • default permissions for the version endpoint

    • version/read

  • default permissions for supervision

    • supervision/read

Replace

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, this query parameter can be omitted.

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

Example

Request
Payload
Response
sourcecurl -XPUT \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/permissions?rev=1" -d \
  '{
      "permissions": [
        "newpermission/read",
        "newpermission/write"
      ]
    }'
source{
  "permissions": [
    "newpermission/read",
    "newpermission/write"
  ]
}
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/permissions-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/permissions",
  "@type": "Permissions",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/permissions.json",
  "_createdAt": "2021-05-10T13:48:58.246Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_rev": 2,
  "_self": "http://localhost:8080/v1/permissions",
  "_updatedAt": "2021-05-10T13:49:26.043Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

Subtract

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
Payload
Response
sourcecurl -XPATCH \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/permissions?rev=2" -d \
  '{
      "@type": "Subtract",
      "permissions": [
        "newpermission/write"
      ]
    }'
source{
  "@type": "Subtract",
  "permissions": [
    "newpermission/write"
  ]
}
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/permissions-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/permissions",
  "@type": "Permissions",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/permissions.json",
  "_createdAt": "2021-05-10T13:48:58.246Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_rev": 1,
  "_self": "http://localhost:8080/v1/permissions",
  "_updatedAt": "2021-05-10T13:49:26.043Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

Append

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
Payload
Response
sourcecurl -XPATCH \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/permissions?rev=3" -d \
  '{
  "@type": "Append",
  "permissions": [
    "newpermission/create"
  ]
}'
source{
  "@type": "Append",
  "permissions": [
    "newpermission/create"
  ]
}
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/permissions-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/permissions",
  "@type": "Permissions",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/permissions.json",
  "_createdAt": "2021-05-10T13:48:58.246Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_rev": 2,
  "_self": "http://localhost:8080/v1/permissions",
  "_updatedAt": "2021-05-10T13:49:26.043Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

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
Response
sourcecurl -XDELETE "http://localhost:8080/v1/permissions?rev=4"
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/permissions-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/permissions",
  "@type": "Permissions",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/permissions.json",
  "_createdAt": "2021-05-10T13:48:58.246Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_rev": 3,
  "_self": "http://localhost:8080/v1/permissions",
  "_updatedAt": "2021-05-10T13:49:26.043Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

Fetch (latest revision)

GET /v1/permissions
Request
Response
sourcecurl "http://localhost:8080/v1/permissions"
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/permissions.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/permissions",
  "@type": "Permissions",
  "permissions": [
    "realms/write",
    "replaced",
    "projects/create",
    "schemas/write",
    "permissions/write",
    "organizations/read",
    "realms/read",
    "resources/read",
    "version/read",
    "acls/read",
    "projects/read",
    "permissions/read",
    "archives/write",
    "organizations/create",
    "views/query",
    "storages/write",
    "resolvers/write",
    "resources/write",
    "acls/write",
    "files/write",
    "events/read",
    "organizations/write",
    "projects/write",
    "views/write"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/permissions.json",
  "_createdAt": "2021-05-10T13:48:58.246Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_rev": 3,
  "_self": "http://localhost:8080/v1/permissions",
  "_updatedAt": "2021-05-10T13:49:26.043Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

Fetch (specific revision)

GET /v1/permissions?rev={rev}

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

Request
Response
sourcecurl "http://localhost:8080/v1/permissions?rev=1"
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/permissions.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/permissions",
  "@type": "Permissions",
  "permissions": [
    "realms/write",
    "replaced",
    "projects/create",
    "schemas/write",
    "permissions/write",
    "organizations/read",
    "realms/read",
    "resources/read",
    "version/read",
    "acls/read",
    "projects/read",
    "permissions/read",
    "archives/write",
    "organizations/create",
    "views/query",
    "storages/write",
    "resolvers/write",
    "resources/write",
    "acls/write",
    "files/write",
    "events/read",
    "organizations/write",
    "projects/write",
    "views/write"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/permissions.json",
  "_createdAt": "2021-05-10T13:48:58.246Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_rev": 3,
  "_self": "http://localhost:8080/v1/permissions",
  "_updatedAt": "2021-05-10T13:49:26.043Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

Server Sent Events

This endpoint allows clients to receive automatic updates from the permissions in a streaming fashion.

GET /v1/permissions/events

where Last-Event-Id is an optional HTTP Header that identifies the last consumed permission event. It can be used for cases when a client does not want to retrieve the whole event stream, but to start after a specific event.

The response contains a series of permission events, represented in the following way

data:{payload}
event:{type}
id:{id}

where…

  • {payload}: Json - is the actual payload of the current permission
  • {type}: String - is a type identifier for the current event. Possible types are: PermissionsAppended, PermissionsSubtracted, PermissionsReplaced and PermissionsDeleted
  • {id}: String - is the identifier of the permission event. It can be used in the Last-Event-Id HTTP Header

Example

Request
Response
sourcecurl \
 "http://localhost:8080/v1/permissions/events"
sourcedata:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/permissions.json"],"@type":"PermissionsReplaced","permissions":["custom"],"_instant":"2021-05-10T13:57:16.947Z","_permissionsId":"http://localhost:8080/v1/permissions","_rev":1,"_subject":"http://localhost:8080/v1/anonymous"}
event:PermissionsReplaced
id:a1532190-b197-11eb-a8e0-49728f9d6e6c

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/permissions.json"],"@type":"PermissionsAppended","permissions":["appended"],"_instant":"2021-05-10T13:57:20.466Z","_permissionsId":"http://localhost:8080/v1/permissions","_rev":2,"_subject":"http://localhost:8080/v1/anonymous"}
event:PermissionsAppended
id:a3690940-b197-11eb-a8e0-49728f9d6e6c

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/permissions.json"],"@type":"PermissionsSubtracted","permissions":["custom"],"_instant":"2021-05-10T13:57:23.119Z","_permissionsId":"http://localhost:8080/v1/permissions","_rev":3,"_subject":"http://localhost:8080/v1/anonymous"}
event:PermissionsSubtracted
id:a4fdda10-b197-11eb-a8e0-49728f9d6e6c

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/permissions.json"],"@type":"PermissionsDeleted","_instant":"2021-05-10T13:59:02.898Z","_permissionsId":"http://localhost:8080/v1/permissions","_rev":4,"_subject":"http://localhost:8080/v1/anonymous"}
event:PermissionsDeleted
id:e0769d20-b197-11eb-a8e0-49728f9d6e6c
v1.8.x