Globus Connect Server Administration Guides
  • Quickstart Guide
  • Installation Guide
  • Data Access Admin Guide
  • Domain Guide
  • HTTPS Access to Collections
  • Identity Mapping Admin Guide
  • Globus OIDC Installation Guide
  • v5.3 Migration Guide
  • Troubleshooting Guide
  • Command-Line Reference
    • Audit
      • Load
      • Query
      • Dump
    • Endpoint
      • Setup
      • Show
      • Update
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Set Owner
      • Set Subscription ID
      • Migrate53
      • Cleanup
      • Domain
      • Role
      • Upgrade
    • OIDC
      • Create
      • Delete
      • Register
      • Show
      • Update
    • Node
      • Create
      • Setup
      • List
      • Show
      • Update
      • Cleanup
      • Update Vhost
      • Delete
    • Login
    • Session
      • Consent
      • Show
      • Update
    • Whoami
    • Logout
    • Storage Gateway
      • Create
      • List
      • Show
      • Update
      • Delete
    • Collection
      • Create
      • List
      • Show
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Update
      • Delete
      • Domain
      • Role
    • Sharing Policy
      • Create
      • List
      • Show
      • Delete
    • Self Diagnostic
  • Globus Connect Server Manager API
    • Responses
    • Schemas
    • Authorization
    • Versioning
    • Endpoint
    • Roles
    • Nodes
    • Storage Gateways
    • Collections
    • User Credentials
    • Domains
    • Sharing Policies
    • ActiveScale
    • Azure Blob
      • Azure Blob
    • BlackPearl
    • Box
    • Ceph
    • Google Cloud Storage
    • Google Drive
    • HPSS
    • iRODS Connector
    • OAuth Credential API
    • OneDrive
    • POSIX Connector
    • POSIX Staging Connector
    • S3
  • API Access for Portals
  • Application Migration Guide
  • Change Log
Skip to main content
Globus Docs
  • APIs
    Auth Transfer Groups Search Python SDK Helper Pages
  • How To
  • Guides
    Globus Connect Server High Assurance Collections for Protected Data Command Line Interface Premium Storage Connectors Globus Automation Services Security Modern Research Data Portal
  • Support
    FAQs Mailing Lists Contact Us Check Support Tickets
  1. Home
  2. Globus Connect Server
  3. Installation Guide
  4. Globus Connect Server Manager API

Endpoint

Endpoint

A GCS Endpoint is an entity that represents an access point to data storage. In GCSv5, this includes the following types of items:

  • One or more Storage Gateways which define policies to access specific data storage rooted in some sort of file system or object store. In this version of the specification, ActiveScale, Azure Blob Storage, BlackPearl, Box, Ceph, Google Drive, Google Cloud Storage, HPSS, iRODS, OneDrive, POSIX, and S3 Storage Gateways are supported.

  • One or more Collections, which may define either a set of data on a Storage Gateway that is shared with other Globus users or publicly, or a set of data on a Storage Gateway that Globus users access with their own local or cloud accounts.

  • One or more nodes which define physical servers providing access to the GCS endpoint resources.

Overview

Method API Path Description

GET

/​endpoint

Get Endpoint

PATCH

/​endpoint

Update Endpoint

PUT

/​endpoint

Update Endpoint

Overview

Method API Path Description

PUT

/​endpoint/​owner

Update the endpoint owner

Overview

Method API Path Description

PUT

/​endpoint/​subscription_id

Update the endpoint subscription

Overview

Method API Path Description

PUT

/​endpoint/​owner_string

Put endpoint owner string

DELETE

/​endpoint/​owner_string

Delete role-based endpoint advertised owner string

Details

Get Endpoint

GET /endpoint

Get the Globus Connect Server’s Endpoint document.

Authorization

  • PublicAuthorizer

  • RoleAuthorizer: [ endpoint:owner, endpoint:administrator, endpoint:activity_manager, endpoint:activity_monitor, collection:administrator:*, collection:activity_manager:*, collection:activity_monitor:*, collection:access_manager:* ]

  • CollectionACLAuthorizer: [ * ]

  • StorageGatewayAuthorizer [ * ]

Responses

200 - Get Endpoint Response
Table 1. application/json

Name

Type

Description

code

success

data

array (object) ( Endpoint )

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": "endpoint#1.0.0",
      "public": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "display_name": "string",
      "gcs_manager_url": "https://gcs.data.globus.org/",
      "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
      "network_use": "normal",
      "max_concurrency": 1,
      "preferred_concurrency": 1,
      "max_parallelism": 1,
      "preferred_parallelism": 1,
      "organization": "string",
      "department": "string",
      "keywords": [
        "string"
      ],
      "description": "string",
      "contact_email": "user@example.com",
      "contact_info": "string",
      "info_link": "http://example.com",
      "allow_udt": false
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}
401 - Unauthorized
403 - Permission Denied

Update Endpoint

PATCH /endpoint

Update the Endpoint document, changing only the properties included in the input. Items explicitly set to null in the input are removed from the Endpoint document. This operation optionally returns the Endpoint after applying the changes in the input if the include=endpoint query parameter is passed to this operation.

Authorization

  • RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Query Parameters

Parameter Type Description

include

array(string) endpoint

List of document types to include in the response.

Request body

application/json

A Globus Connect Server endpoint is a deployment of Globus Connect Server version 5. A single endpoint may optionally include multiple data transfer nodes. The endpoint provides a link between a Globus Connect Server deployment and the Globus Transfer service. The endpoint describes services for accessing data via GridFTP and HTTPS and also for configuring and managing the policies associated with that access.

Name

Type

Description

DATA_TYPE

string endpoint#1.0.0

Type of this document

public

boolean

Flag indicating whether this endpoint is visible to all other Globus users. If false, only users which have been granted a role on the endpoint or one of its collections, or belong to a domain allowed access to any of its storage gateways may view it.

display_name

string

Friendly name for the endpoint, not unique. Unicode string, no new lines (\r or \n). Searchable.

subscription_id

string anyOf { <uuid>, DEFAULT }

The UUID of the subscription that is managing this endpoint. This may be the special value DEFAULT when using this as input to PATCH or PUT to use the caller’s default subscription id.

network_use

string normal, minimal, aggressive, custom

Allowed values for network_use are:

normal

The default setting. Uses an average level of concurrency and parallelism. The levels depend on the number of physical servers in the endpoint.

minimal

Uses a minimal level of concurrency and parallelism.

aggressive

Uses a high level of concurrency and parallelism.

custom

Uses custom values of concurrency and parallelism set by the endpoint admin. When setting this level, you must also set the max_concurrency, preferred_concurrency, max_parallelism, and preferred_parallelism options.

max_concurrency

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

preferred_concurrency

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

max_parallelism

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

preferred_parallelism

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

organization

string

Organization that runs the server(s) represented by the endpoint. Optional to preserve backward compatibility, but will eventually be required and all clients are encouraged to require users to specify it. Unicode string, max 1024 characters, no new lines.

department

string

Department within organization that runs the server(s). Searchable. Optional. Unicode string, max 1024 characters, no new lines.

keywords

array (string)

List of search keywords for the endpoint. Optional. Unicode string, max 1024 characters total across all strings.

description

string

A description of the endpoint.

contact_email

string <email>

Email address of the support contact for the server(s) represented by the endpoint.

contact_info

string

Other non-email contact information for the endpoint, e.g. phone and mailing address.

info_link

string <uri>

Link to a web page with more information about the endpoint. The administrator is responsible for running a website at this URL and verifying that it is accepting public connections.

allow_udt

boolean

Allow data transfer on this endpoint using the UDT protocol.

Example
{
  "DATA_TYPE": "endpoint#1.0.0",
  "public": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "display_name": "string",
  "gcs_manager_url": "https://gcs.data.globus.org/",
  "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
  "network_use": "normal",
  "max_concurrency": 1,
  "preferred_concurrency": 1,
  "max_parallelism": 1,
  "preferred_parallelism": 1,
  "organization": "string",
  "department": "string",
  "keywords": [
    "string"
  ],
  "description": "string",
  "contact_email": "user@example.com",
  "contact_info": "string",
  "info_link": "http://example.com",
  "allow_udt": false
}

Responses

200 - Update Endpoint Response.
Table 2. application/json

Name

Type

Description

code

string success

data

array (object) ( Endpoint )

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": "endpoint#1.0.0",
      "public": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "display_name": "string",
      "gcs_manager_url": "https://gcs.data.globus.org/",
      "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
      "network_use": "normal",
      "max_concurrency": 1,
      "preferred_concurrency": 1,
      "max_parallelism": 1,
      "preferred_parallelism": 1,
      "organization": "string",
      "department": "string",
      "keywords": [
        "string"
      ],
      "description": "string",
      "contact_email": "user@example.com",
      "contact_info": "string",
      "info_link": "http://example.com",
      "allow_udt": false
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}
400 - Bad request
401 - Unauthorized
403 - Missing required role
415 - UnsupportedMedia
422 - UnprocessableEntity

Update Endpoint

PUT /endpoint

Update the Endpoint document, replacing all properties with those in the input. This operation optionally returns the Endpoint after the update if the include=endpoint query parameter is passed to this operation.

Authorization

  • RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Query Parameters

Parameter Type Description

include

array(string) endpoint

List of document types to include in the response.

Request body

application/json

A Globus Connect Server endpoint is a deployment of Globus Connect Server version 5. A single endpoint may optionally include multiple data transfer nodes. The endpoint provides a link between a Globus Connect Server deployment and the Globus Transfer service. The endpoint describes services for accessing data via GridFTP and HTTPS and also for configuring and managing the policies associated with that access.

Name

Type

Description

DATA_TYPE

string endpoint#1.0.0

Type of this document

public

boolean

Flag indicating whether this endpoint is visible to all other Globus users. If false, only users which have been granted a role on the endpoint or one of its collections, or belong to a domain allowed access to any of its storage gateways may view it.

display_name

string

Friendly name for the endpoint, not unique. Unicode string, no new lines (\r or \n). Searchable.

subscription_id

string anyOf { <uuid>, DEFAULT }

The UUID of the subscription that is managing this endpoint. This may be the special value DEFAULT when using this as input to PATCH or PUT to use the caller’s default subscription id.

network_use

string normal, minimal, aggressive, custom

Allowed values for network_use are:

normal

The default setting. Uses an average level of concurrency and parallelism. The levels depend on the number of physical servers in the endpoint.

minimal

Uses a minimal level of concurrency and parallelism.

aggressive

Uses a high level of concurrency and parallelism.

custom

Uses custom values of concurrency and parallelism set by the endpoint admin. When setting this level, you must also set the max_concurrency, preferred_concurrency, max_parallelism, and preferred_parallelism options.

max_concurrency

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

preferred_concurrency

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

max_parallelism

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

preferred_parallelism

integer

Admin-specified value when the network_use property’s value is custom; otherwise the preset value for the specified network_use.

organization

string

Organization that runs the server(s) represented by the endpoint. Optional to preserve backward compatibility, but will eventually be required and all clients are encouraged to require users to specify it. Unicode string, max 1024 characters, no new lines.

department

string

Department within organization that runs the server(s). Searchable. Optional. Unicode string, max 1024 characters, no new lines.

keywords

array (string)

List of search keywords for the endpoint. Optional. Unicode string, max 1024 characters total across all strings.

description

string

A description of the endpoint.

contact_email

string <email>

Email address of the support contact for the server(s) represented by the endpoint.

contact_info

string

Other non-email contact information for the endpoint, e.g. phone and mailing address.

info_link

string <uri>

Link to a web page with more information about the endpoint. The administrator is responsible for running a website at this URL and verifying that it is accepting public connections.

allow_udt

boolean

Allow data transfer on this endpoint using the UDT protocol.

Example
{
  "DATA_TYPE": "endpoint#1.0.0",
  "public": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "display_name": "string",
  "gcs_manager_url": "https://gcs.data.globus.org/",
  "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
  "network_use": "normal",
  "max_concurrency": 1,
  "preferred_concurrency": 1,
  "max_parallelism": 1,
  "preferred_parallelism": 1,
  "organization": "string",
  "department": "string",
  "keywords": [
    "string"
  ],
  "description": "string",
  "contact_email": "user@example.com",
  "contact_info": "string",
  "info_link": "http://example.com",
  "allow_udt": false
}

Responses

200 - Endpoint Update Response
Table 3. application/json

Name

Type

Description

code

string success

data

array (object) ( Endpoint )

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": "endpoint#1.0.0",
      "public": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "display_name": "string",
      "gcs_manager_url": "https://gcs.data.globus.org/",
      "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
      "network_use": "normal",
      "max_concurrency": 1,
      "preferred_concurrency": 1,
      "max_parallelism": 1,
      "preferred_parallelism": 1,
      "organization": "string",
      "department": "string",
      "keywords": [
        "string"
      ],
      "description": "string",
      "contact_email": "user@example.com",
      "contact_info": "string",
      "info_link": "http://example.com",
      "allow_udt": false
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}
400 - Bad request
401 - Unauthorized
403 - Missing required role
415 - UnsupportedMedia
422 - UnprocessableEntity

Details

Update the endpoint owner

PUT /endpoint/owner

Assign a new identity to act as the endpoint owner.

Authorization

  • RoleAuthorizer: [ endpoint:owner ]

Request body

application/json

Owner document.

Name

Type

Description

DATA_TYPE

string endpoint_owner#1.0.0

Type of this document

identity_id

string <uuid>

Auth identity ID of the endpoint owner

Example
{
  "DATA_TYPE": "endpoint_owner#1.0.0",
  "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1"
}

Responses

200 - Owner update Response
Table 4. application/json

Name

Type

Description

code

string success

data

array (object)

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": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}
400 - Bad request
401 - Unauthorized
403 - Missing required role
415 - UnsupportedMedia
422 - UnprocessableEntity

Details

Update the endpoint subscription

PUT /endpoint/subscription_id

Change the subscription_id of this endpoint. Because subscription is enforcement is handled in a separate service than GCS and an organization’s subscription manager may not be the administrator of the endpoint, this API has allows for both role-based authorization and subscription manager based authorization.

The authorization allows the following:

Caller has a role but is not subscription manager

Remove an existing subscription from an endpoint, even if the callers is not a manager for that subscription.

Caller does not have a role but is a subscription manager

Set the subscription_id to a subscription they manage on a currently-unmanaged endpoint.

Caller has a role and is a subscription manager

Set the subscription_id to a subscription they manage on an endpoint even if it is currently managed by a subscription that the caller is not a manager of.

Authorization

  • RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

  • SubscriptionManagerAuthorizer

Request body

application/json

Endpoint subscription request document

Name

Type

Description

DATA_TYPE

string endpoint_subscription#1.0.0

Type of this document

subscription_id

One of { string <uuid>, string DEFAULT​ }

Either the UUID of a Globus subscription or the special value "DEFAULT" if the caller has only one subscription associated with their identity set.

Example
{
  "DATA_TYPE": "endpoint_subscription#1.0.0",
  "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896"
}

Responses

200 - Owner update Response
Table 5. application/json

Name

Type

Description

code

string success

data

array (object)

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": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}
400 - Bad request
401 - Unauthorized
403 - Missing required role
415 - UnsupportedMedia
422 - UnprocessableEntity

Details

Put endpoint owner string

PUT /endpoint/owner_string

Modify the endpoint’s advertised owner to match the username of one of the caller’s linked identities. The identity must have an administrator role on the endpoint.

Authorization

  • RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Request body

application/json

Owner string document.

Name

Type

Description

DATA_TYPE

string owner_string#1.0.0

Type of this document

identity_id

string <uuid>

Auth identity username

Example
{
  "DATA_TYPE": "owner_string#1.0.0",
  "identity_id": "2574c430-0c01-4695-92fa-4bad3c21f6ab"
}

Responses

200 - Set endpoint owner string response
Table 6. 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"
}
400 - Bad request
401 - Unauthorized
403 - Missing required role
404 - Not Found
415 - UnsupportedMedia
422 - UnprocessableEntity

Delete role-based endpoint advertised owner string

DELETE /endpoint/owner_string

Reset the endpoint’s advertised owner to the client_id of the endpoint.

Authorization

  • RoleAuthorizer: [ endpoint:administrator, endpoint:owner ]

Responses

200 - Reset endpoint owner string response
Table 7. 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"
}
400 - Bad request
401 - Unauthorized
403 - Missing required role
415 - UnsupportedMedia
422 - UnprocessableEntity
  • Quickstart Guide
  • Installation Guide
  • Data Access Admin Guide
  • Domain Guide
  • HTTPS Access to Collections
  • Identity Mapping Admin Guide
  • Globus OIDC Installation Guide
  • v5.3 Migration Guide
  • Troubleshooting Guide
  • Command-Line Reference
    • Audit
      • Load
      • Query
      • Dump
    • Endpoint
      • Setup
      • Show
      • Update
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Set Owner
      • Set Subscription ID
      • Migrate53
      • Cleanup
      • Domain
      • Role
      • Upgrade
    • OIDC
      • Create
      • Delete
      • Register
      • Show
      • Update
    • Node
      • Create
      • Setup
      • List
      • Show
      • Update
      • Cleanup
      • Update Vhost
      • Delete
    • Login
    • Session
      • Consent
      • Show
      • Update
    • Whoami
    • Logout
    • Storage Gateway
      • Create
      • List
      • Show
      • Update
      • Delete
    • Collection
      • Create
      • List
      • Show
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Update
      • Delete
      • Domain
      • Role
    • Sharing Policy
      • Create
      • List
      • Show
      • Delete
    • Self Diagnostic
  • Globus Connect Server Manager API
    • Responses
    • Schemas
    • Authorization
    • Versioning
    • Endpoint
    • Roles
    • Nodes
    • Storage Gateways
    • Collections
    • User Credentials
    • Domains
    • Sharing Policies
    • ActiveScale
    • Azure Blob
      • Azure Blob
    • BlackPearl
    • Box
    • Ceph
    • Google Cloud Storage
    • Google Drive
    • HPSS
    • iRODS Connector
    • OAuth Credential API
    • OneDrive
    • POSIX Connector
    • POSIX Staging Connector
    • S3
  • API Access for Portals
  • Application Migration Guide
  • Change Log
© 2010- The University of Chicago Legal Privacy Accessibility