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 GCS Manager Roles document for more information on the meaning of the roles. All API endpoints below indicate which roles are required to perform the given operation.

Overview

Method	API Path	Description
`POST`	/roles	Create Role
`GET`	/roles	List Roles

Overview

Method	API Path	Description
`DELETE`	/roles/{role_id}	Delete a Role
`GET`	/roles/{role_id}	Get a Role

Common Path Parameters

Parameter	Type	Description
role_id (required)	string Any	ID of the Role

Details

Create Role

POST /roles

Assign a role to an identity or group for the Endpoint or a specified 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

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
collection	string <uuid>	Collection Id. This value is omitted when creating an endpoint role or when creating role definitions when creating collections.
principal	string `^(urn:globus:auth:identity\|urn:globus:groups:id):[a-f0-9-]*$`	Auth identity or group id URN.
role	string `owner`, `administrator`, `access_manager`, `activity_manager`, `activity_monitor`	Role assigned to the principal.

Example

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

Responses

200 - Create Role response

Table 1. application/json
Name	Type	Description
code	string `success`
data	array ( Role )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
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.
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.

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

409 - Exists or Conflict Response

Table 2. application/json
Name	Type	Description
code	string `exists`, `conflict`
http_response_code	`409`
DATA_TYPE	string `result#1.0.0`	Type of this document.
detail		Machine readable response details
message	string	Message describing this result.
data	array (object)
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.
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.

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

List Roles

GET /roles

Get the Globus Connect Server Endpoint’s or a Collection’s list of Role documents.

If the collection_id query parameter is passed to this operation, then the roles related to that Collection are returned, otherwise only Endpoint roles are returned.

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

To obtain information about roles for other identities, 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:administrator, collection:administrator:{collection_id} ]

Query Parameters

Parameter	Type	Description
include	string `all_roles`	Flag indicating whether to request all roles assignments for the Endpoint or Collection.
marker	string Any	Pagination marker for a paginated response
page_size	integer Any	Maximum page size for a paginated response
collection_id	string Any	ID of the Collection

Responses

200 - Get roles result

Table 3. application/json
Name	Type	Description
code	string `success`
data	array ( Role )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
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.
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.

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

Details

Delete a Role

DELETE /roles/{role_id}

Delete one of the Globus Connect Server’s Role documents by its ID.

Authorization

RoleAuthorizer: [ endpoint:administrator, collection:administrator:{collection_id} ]

Responses

200 - Delete Role result

Table 4. application/json
Name	Type	Description
code	string `success`
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
data	array (object)
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.
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.

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

Get a Role

GET /roles/{role_id}

Get one of the Globus Connect Server’s Role documents by its ID.

Authorization

RoleAuthorizer: [ endpoint:administrator, collection:administrator:{collection_id} ]

Responses

200 - Get role result

Table 5. application/json
Name	Type	Description
code	string `success`
data	array ( Role )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
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.
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.

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