Roles

The client identity that created an Endpoint has full control over management aspects of the endpoint, including the properties, collections, the ACL, and role assignments. Other roles enable other identities to act on various subsets of endpoint and collection management capabilities. See the endpoint roles and collection roles reference pages for information about the roles. All API endpoints below indicate which roles are required to perform the given operation.

Roles Overview

Method	API Path	Description
`GET`	/api/roles	List roles
`POST`	/api/roles	Create a role
`DELETE`	/api/roles/{role_id}	Delete a role
`GET`	/api/roles/{role_id}	Get a role

Details

List roles

GET /api/roles

Get the endpoint’s or a collection’s list of role associations.

If the collection_id query parameter is passed to this operation, then the roles related to that collection are returned. Otherwise, this operation returns endpoint roles.

The include parameter determines whether this operation returns all roles relevant to the resource or only those that the caller has.

To obtain information about all roles, the caller must pass the "all_roles" value as the value of the "include" parameter. This requires the "administrator" role for the endpoint Or Collection the role is associated with.

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator
- collection:administrator:{collection_id}

Query Parameters

Parameter	Type	Description
page_size	integer <int>	Maximum page size for a paginated response
marker	string	Pagination marker for a paginated response
collection_id	string <uuid>	ID of the collection
include	array of string `all_roles`	Flag indicating whether to request all roles assignments for the endpoint or collection.

Responses

200 - List roles response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `success`	String response code
data	array of object Role
detail	any type
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "data": [
    {
      "DATA_TYPE": "role#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "principal": "string",
      "collection": "65986b24-c0b1-41fa-b21f-4a319273f511",
      "role": "owner"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `permission_denied`	String response code
data	array of object
detail	string or MissingRequiredRole
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `403`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

Create a role

POST /api/roles

Assign a role to an identity or group for the endpoint or a collection.

See endpoint roles and collection roles for description of the available roles.

To assign a role to a collection, include the collection’s ID in the collection property of the input document.

When creating an endpoint role, the caller must have then endpoint:administrator role assigned to one of their identities.

When creating a collection role for a mapped collection, the caller must have either the endpoint:administrator role or the collection:administrator role assigned for that collection.

When creating a collection role for a guest collection, the caller must have a collection:administrator role on the collection.

On success returns a copy of the created role with the system generated id added.

Authorization

RoleAuthorizer:
- endpoint:administrator
- collection:administrator:{collection_id}

Request body

Content-Type: application/json

The "Role" document type represents the assignment of a role on an Endpoint or Collection to a Globus identity or group.

Name	Type	Description
DATA_TYPE	string `role#1.0.0`	Type of this document
id	string <uuid>	Unique id string for this role assignment. This is system generated and should not be included in create requests.
principal	string `^(urn:globus:auth:identity\|urn:globus:groups:id):([a-f0-9-]*)$`	Globus Auth identity or group id URN
collection	string <uuid>	Collection Id. This value is omitted when creating an endpoint role or when creating role definitions when creating "collections.
role	string `owner`, `administrator`, `access_manager`, `activity_manager`, `activity_monitor`, `access_monitor`	Role assigned to the principal

Example

{
  "DATA_TYPE": "role#1.0.0",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "principal": "string",
  "collection": "65986b24-c0b1-41fa-b21f-4a319273f511",
  "role": "owner"
}

Responses

200 - Create role response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `success`	String response code
data	array of object Role
detail	any type
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "data": [
    {
      "DATA_TYPE": "role#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "principal": "string",
      "collection": "65986b24-c0b1-41fa-b21f-4a319273f511",
      "role": "owner"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}

400 - Bad Request

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `bad_request`	String response code
data	array of object
detail	any type
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `400`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "http_response_code": 100,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "detail": null,
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

One of the following schemas:

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `permission_denied`	String response code
data	array of object
detail	string or MissingRequiredRole
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `403`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `subscription_required`	String response code
data	array of object
detail	string or SubscriptionRequired
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `403`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

409 - Conflict

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `exists`	String response code
data	array of object
detail	any type
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `409`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "http_response_code": 100,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "detail": null,
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

415 - Unsupported media type

422 - Unprocessable entity

Details

Delete a role

DELETE /api/roles/{role_id}

Delete one of the endpoint or collection roles on this endpoint.

To delete an endpoint role, the caller must have an endpoint:administrator role.

To delete a mapped collection role, the caller must have one of endpoint:administrator or collection:administrator role for the collection.

To delete a guest collection role, the caller must have one of endpoint:administrator, collection:administrator role for the guest collection, or collection:administrator for the mapped collection the guest collection was created on.

The endpoint:owner, or the collection:administrator role for the creator of a collection may not be deleted using this API.

Authorization

RoleAuthorizer:
- endpoint:administrator
- collection:administrator:{collection_id}
- collection:administrator:{mapped_collection_id}

Path parameters

▷ role_id

Id of the role

Parameter	Type	Description
role_id (required)	string <uuid>	Id of the role

Responses

200 - Delete role response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string	String response code
data	array of object
detail	any type
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "DATA_TYPE": "result#1.0.0",
  "code": "string",
  "data": [
    {}
  ],
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

One of the following schemas:

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `permission_denied`	String response code
data	array of object
detail	string or MissingRequiredRole
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `403`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `subscription_required`	String response code
data	array of object
detail	string or SubscriptionRequired
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `403`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

404 - Not found

409 - Conflict

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `conflict`	String response code
data	array of object
detail	any type
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `409`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "http_response_code": 100,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "detail": null,
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

Get a role

GET /api/roles/{role_id}

Get one of the role assignments on this endpoint.

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator
- collection:administrator:{collection_id}

Path parameters

▷ role_id

Id of the role

Parameter	Type	Description
role_id (required)	string <uuid>	Id of the role

Responses

200 - Get role response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `success`	String response code
data	array of object Role
detail	any type
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "data": [
    {
      "DATA_TYPE": "role#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "principal": "string",
      "collection": "65986b24-c0b1-41fa-b21f-4a319273f511",
      "role": "owner"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string `permission_denied`	String response code
data	array of object
detail	string or MissingRequiredRole
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
http_response_code	integer `403`	Numeric HTTP response code
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.
message	string	Message describing this result

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}