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.
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
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 global event log
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
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" ] }'
- Payload
-
{ "permissions": [ "newpermission/read", "newpermission/write" ] }
- 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" }
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" ] }'
- Payload
-
{ "@type": "Subtract", "permissions": [ "newpermission/write" ] }
- 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" }
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" ] }'
- Payload
-
{ "@type": "Append", "permissions": [ "newpermission/create" ] }
- 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" }
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"
- 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" }
Fetch permissions (latest revision)
GET /v1/permissions
- Request
-
curl "https://nexus.example.com/v1/permissions"
- 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" }
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"
- 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" }
Permissions 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 permission. Possible types are: PermissionsAppended, PermissionsSubtracted, PermissionsReplaced and PermissionsDeleted{id}
: String - is the identifier of the permission event. It can be used in theLast-Event-Id
HTTP Header
Example
- Request
-
curl "https://nexus.example.com/v1/permissions/events"
- Response
-
data:{"@context":["https://bluebrain.github.io/nexus/contexts/iam.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"PermissionsAppended","permissions":["resources/write","views/query"],"_rev":1,"_instant":"2019-06-14T11:57:04.039Z","_subject":"https://nexus.example.com/v1/realms/nexusdev/users/myuser"} event:PermissionsAppended id:8693f7b0-8e9b-11e9-a8f6-c5c16f2312d6 data:{"@context":["https://bluebrain.github.io/nexus/contexts/iam.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"PermissionsSubtracted","permissions":["views/query"],"_rev":2,"_instant":"2019-06-14T11:57:05.771Z","_subject":"https://nexus.example.com/v1/realms/nexusdev/users/myuser"} event:PermissionsSubtracted id:879c3ff0-8e9b-11e9-a8f6-c5c16f2312d6 data:{"@context":["https://bluebrain.github.io/nexus/contexts/iam.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"PermissionsReplaced","permissions":["schemas/write","views/write","files/write","permissions/write","acls/write","realms/write","projects/read","acls/read","organizations/create","tcmbsyeq/rcxpdxng","organizations/write","resources/write","realms/read","projects/create","storages/write","permissions/read","resources/read","organizations/read","resolvers/write","events/read","views/query","projects/write"],"_rev":3,"_instant":"2019-06-14T11:57:07.277Z","_subject":"https://nexus.example.com/v1/realms/nexusdev/users/myuser"} event:PermissionsReplaced id:88820c10-8e9b-11e9-a8f6-c5c16f2312d6