Endpoint Management

1. Overview

Endpoints are named entities that represent a gridftp or other file transfer service server. They have a globally unique id, and a not necessarily unique display name. The API for manipulating endpoint definitions is located under /endpoint/.

Note

Endpoints were formerly identified by a globally unique, username qualified name, called the "canonical name". These names still exist but are deprecated and will be removed in the future.

For operations that can be performed on an endpoint’s filesystem, see File Operations.

For delegating rights for managing various aspects of the endpoint’s administration to other users, see Endpoint Roles.

For getting list of endpoints matching a name or other categories, see Endpoint Search.

1.1. Linked Identities

Authorization is based on the capabilities granted to any of the linked identities associated with the Globus Auth token used to authenticate to the REST API, combined with capabilities granted to any of the groups any of the linked identities belong too. For example, a private endpoint will be visible if any of the linked identities own the endpoint, or if any of the linked identities has an appropriate effective role on the endpoint (see role documentation for details on which roles grant this visibility).

When an endpoint is created, the owner_id and owner_string are set based on the primary identity. Note that owner_string can be changed; see the field documentation for details.

1.2. "Managed" Endpoints

Some advanced endpoint features, for example hosting shared endpoints and using the Advanced Endpoint Management API, require a Globus subscription. To enable these features for an endpoint, the endpoint must be set as "managed" by setting the subscription_id field on the endpoint to the id for the subscription. Once this is set, the endpoint is considered "managed". Shared endpoints, Globus Connect Server v5 collections, and Globus Connect Personal guest collections cannot have a subscription_id set on them directly, but will inherit the value and managed behaviors from their parent entities.

2. Document Types

2.1. Endpoint Document

The "endpoint" document type represents a single transfer endpoint, and contains a list of "server" documents in the "DATA" section, representing the GridFTP server or servers used to access the endpoint.

Fields marked as [GCSv4] are only applicable to Globus Connect Server v4 endpoints, and will be deprecated when support for Globus Connect Server v4 ends.

2.1.1. Types of Endpoints

Endpoint type can be determined via the entity_type field. Note that for Globus Connect Personal and Globus Connect Server v5 the value will use the term "collection" for entities that allow data access and "endpoint" for entities that do not. The Transfer API in general does not make this distinction and will refer to all of these entities as "endpoints" in most cases.

GCSv4_host

This category primarily includes endpoints configured using the Globus Connect Server v4 package. It can however also include older versions and manually configured GridFTP endpoints, as Transfer does not distinguish between these in the endpoint document. To function, these endpoints must have at least one server sub-document, and generally require activation before use.

GCSv4_share

This category includes shares created off GCSv4 hosts. Their host_endpoint_id will be non null and set to their host endpoint’s id. These endpoints do not require activation before use, and like guest collections have their access controlled by ACL permissions created in Transfer.

GCP_mapped_collection

These entities represent top level installs of Globus Connect Personal. They are managed in Transfer, and do not require activation for use. The gcp_connected field can be used to determine if the Globus Connect Personal client is currently running and connected to Globus.

GCP_guest_collection

This category is made up of guest collections created to share data from a Globus Connect Personal mapped collection. Their host_endpoint_id will be non null and set to the GCP mapped collection. Like GCSv4 shares and GCSv5 guest collections access is controlled by ACL permissions created in Transfer.

Note

Globus Connect Server v5 entities are read only in Transfer. They should instead be managed by the GCS Manager API, which can be reached at the gcs_manager_url present in the endpoint document.

GCSv5_endpoint

These entities are the top level installation of a Globus Connect Server v5 used for administration and configuration across the installation. They cannot be used for data access, and as such will have non_functional set to "true".

GCSv5_mapped_collection

These entities are used for accessing data via mapping Globus Auth identities to local accounts. They will have a non null non_functional_endpoint_id that refers to their host endpoint. All GCSv5 mapped collections will have an authentication_timeout_mins set, and if the high_assurance field is set to "false", then the mapped collection will require a data_access consent before it may be accessed.

GCSv5_guest_collection

GCSv5 guest collections are created off a GCSv5 mapped collection and are used for sharing access with Globus Auth identities that do not have mappings to local accounts. They will have both a non null non_functional_endpoint_id that refers to their GCSv5 host endpoints, and a non null mapped_collection_id that refers to the mapped collection they provide access to. Like GCSv4 shares and GCP guest collections access is controlled by ACL permissions created in Transfer.

Note

If a host endpoint is deleted, all hosted shared endpoints will stop allowing filesystem operations (task submission and interactive operations). The API resources will return a "Conflict" error in this case.

Endpoint Document Example

{
  "DATA": [
    {
      "DATA_TYPE": "server",
      "hostname": "gridftp.example.org",
      "id": 985,
      "incoming_data_port_end": null,
      "incoming_data_port_start": null,
      "is_connected": true,
      "is_paused": false,
      "outgoing_data_port_end": null,
      "outgoing_data_port_start": null,
      "port": 2811,
      "scheme": "gsiftp",
      "subject": "/O=Grid/OU=Example/CN=host/gridftp.example.org",
      "uri": "gsiftp://gridftp.example.org:2811"
    }
  ],
  "DATA_TYPE": "endpoint",
  "acl_available": false,
  "acl_editable": false,
  "activated": false,
  "authentication_assurance_timeout": null,
  "authentication_policy_id": null,
  "authentication_timeout_mins": null,
  "canonical_name": "go#a6b19eb6-dcb1-11ea-9ef7-0aba3c43875b",
  "contact_email": "me@example.com",
  "contact_info": null,
  "default_directory": null,
  "department": "Example Studies",
  "description": "Example endpoint",
  "disable_anonymous_writes": false,
  "disable_verify": false,
  "display_name": "Example",
  "entity_type": "GCSv4_endpoint",
  "expire_time": "2000-01-02 03:45:06+00:00",
  "expires_in": 0,
  "force_encryption": false,
  "force_verify": false,
  "french_english_bilingual": false,
  "gcp_connected": null,
  "gcp_paused": null,
  "gcs_manager_url": null,
  "gcs_version": null,
  "globus_connect_setup_key": null,
  "high_assurance": false,
  "host_endpoint": null,
  "host_endpoint_display_name": null,
  "host_endpoint_id": null,
  "host_path": null,
  "https_server": null,
  "id": "096a65b1-3e90-44e6-9cb4-550b2d5401c0",
  "in_use": false,
  "info_link": null,
  "is_globus_connect": false,
  "is_go_storage": false,
  "keywords": "Example Endpoint",
  "last_accessed_time": null,
  "local_user_info_available": true,
  "location": "Automatic",
  "mapped_collection_display_name": null,
  "mapped_collection_id": null,
  "max_concurrency": 4,
  "max_parallelism": 4,
  "mfa_required": false,
  "my_effective_roles": [
    "administrator",
    "activity_manager",
    "activity_monitor"
  ],
  "myproxy_dn": null,
  "myproxy_server": null,
  "name": "096a65b1-3e90-44e6-9cb4-550b2d5401c0",
  "network_use": "normal",
  "non_functional": false,
  "non_functional_endpoint_display_name": null,
  "non_functional_endpoint_id": null,
  "oauth_server": null,
  "organization": "My Org",
  "owner_id": "7f0c5933-f28a-4bea-bd8a-e4d5d04637b5",
  "owner_string": "auser@globusid.org",
  "preferred_concurrency": 2,
  "preferred_parallelism": 2,
  "public": false,
  "requester_pays": false,
  "s3_owner_activated": false,
  "s3_url": null,
  "shareable": true,
  "sharing_target_endpoint": null,
  "sharing_target_root_path": null,
  "storage_type": null,
  "subscription_id": "4d8920a8-6cbb-4d3e-93f0-ce59a476fa01",
  "tlsftp_server": null,
  "user_message": null,
  "user_message_link": null,
  "username": "auser"
}

2.1.2. Endpoint Fields

Field Name	JSON Type	Description
DATA	array of objects	A list of server documents. Can be empty.
DATA_TYPE	string	Always has value "endpoint" to indicate this document type.
acl_available	boolean	"true" for endpoints that support the ACL resources
acl_editable	boolean	[DEPRECATED] use `my_effective_roles` instead.
activated	boolean	[GCSv4] "true" if the endpoint is activated, "false" otherwise.
authentication_assurance_timeout	integer	[DEPRECATED] Use `high_assurance` and `authentication_timeout_mins` instead.
authentication_policy_id	string	UUID for an authentication policy. Only applies to Globus Connect Server v5 guest collections.
authentication_timeout_mins	integer	This value is the timeout, in minutes, for high-assurance sessions and mapped collection data access. Only Globus Auth identities that have authenticated within the timeout will be used. Note that `@clients.auth.globus.org` identities are exempt from this timeout.
canonical_name	string	[DEPRECATED] Use `id` and `display_name` instead.
contact_email	string	Email address of the support contact for the server(s) represented by the endpoint. ASCII string, must be a valid email address. Optional.
contact_info	string	Other non-email contact information for the endpoint, e.g. phone and mailing address. Unicode string, can contain new lines, max 4096 characters. Optional.
default_directory	string	Default directory to display when an endpoint is first accessed in the `app.globus.org` web interface. The default behavior if not specified depends on entity and connector type, but will typically be the local user’s home directory when available or the root of the collection. Optional. IMPORTANT The Transfer Endpoint Document only provides this information for GCP entities (i.e. `GCP_mapped_collection` and `GCP_guest_collection`). For other entity types, this is a read-only value set to `/{server_default}/`. In these cases, the property should be managed via GCS API.
department	string	Department within organization that runs the endpoint. Unicode string, max 1024 characters, no new lines. Searchable. Optional.
description	string	A description of the endpoint. Unicode string, max length 4000 characters. Searchable. Optional.
disable_anonymous_writes	boolean	This option indicates that the endpoint does not allow anonymous write permissions. Any such permissions that already exist will be treated as read only, and attempts to create new anonymous write permissions will raise errors. This option may only be set directly on Globus Connect Server v5 mapped collections, but the flag and behavior will apply to all guest collections whose mapped collection have this set.
disable_verify	boolean	This option indicates that the endpoint does not support computing MD5 checksums, needed for the `verify_checksum` option of transfer. When this is set on the endpoint or its host, transfer submissions will have checksum verification disabled. Mutually exclusive with force_verify. A task cannot be submitted with source and destination endpoints that have conflicting `disable_verify` and `force_verify` options. Default: see note.
display_name	string	Friendly name for the endpoint, not unique. Unicode string, max 128 characters, no new lines (\r or \n). Searchable.
entity_type	string	The type of endpoint or collection this endpoint document refers to. See Types of Endpoints above for details.
expire_time	string	[GCSv4] Date and time the endpoint activation expires, or null if not activated. Formatted as ISO 8601 but with space instead of "T" separating the date and time portions.
expires_in	int	[GCSv4] Seconds until the endpoint expires, 0 if the endpoint is expired or not activated, or -1 for entity types that don’t require activation.
force_encryption	boolean	If set to true on the endpoint or its host, all transfer to or from the endpoint will have the encryption option automatically turned on regardless of the user’s initial submission options. If false, users can decide whether or not to enable encryption. Default: false. If this is a high-assurance endpoint, this field will always be true, and updates will be ignored.
force_verify	boolean	If set to true on the endpoint or its host all transfer submissions will have checksum verification enabled. Mutually exclusive with `disable_verify`. A task cannot be submitted with source and destination endpoints that have conflicting `disable_verify` and `force_verify` options. Default: see note.
french_english_bilingual	boolean	If this flag is set, notification emails sent by the Transfer service that involve this endpoint will include both French and English text.
gcp_connected	boolean	For Globus Connect Personal mapped collections this indicates if the software is running and connected to Globus. "null" for other entity types including Globus Connect Personal guest collections.
gcp_paused	boolean	For Globus Connect Personal mapped collections this indicates if the software has paused the connection. "null" for other entity types including Globus Connect Personal guest collections.
gcs_manager_url	string	For Globus Connect Server v5 endpoints and collections, this value will be the url for that Globus Connect Server v5 installation’s Globus Connect Server Manager API. For other entity types this field will be null.
gcs_version	string	SemVer string of Globus Connect Server version information given by Globus Connect Server. Will be null for Globus Connect Server endpoints that do not report version information and Connect Personal endpoints. Read only, will not be recognized on POST or PUT requests.
globus_connect_setup_key	string	Key needed to complete Globus Connect Personal installation. "null" when installation setup is complete. The key can only be used once. Always "null" for non personal endpoints.
high_assurance	boolean	This flag marks an endpoint as a high-assurance resource for data and API access. See high assurance for more information. The endpoint must have an `authentication_timeout_mins` set for this flag to be set as true. If the flag is set as true, the endpoint must also have a subscription at the High Assurance tier before data access and access management are allowed. This flag cannot be updated.
host_endpoint	string	[DEPRECATED] Use `host_endpoint_id` and `host_endpoint_display_name` instead.
host_endpoint_display_name	string	If the host endpoint has not been deleted and the user has authorization for Get endpoint by id on the host endpoint, this will be set to the `display_name` of the host endpoint. "null" if the host endpoint has been deleted, if the user does not have permission, or if the endpoint is not a shared endpoint.
host_endpoint_id	string	ID of standard endpoint hosting the shared endpoint; "null" for non-shared endpoints. Note that this will be set on all shared endpoints, regardless of whether the user has permission to get details of the endpoint or whether the endpoint has been deleted.
host_path	string	Root path being shared on the host endpoint, if the endpoint is a shared endpoint and if the user has the "administrator" effective role on the shared endpoint or the "activity_monitor" effective role on the host endpoint. "null" if the host endpoint has been deleted, if the user does not have one of the required effective roles, or if the endpoint is not a shared endpoint. Globus Connect Server v5 guest collections and high assurance Globus Connect Personal guest collections will have this set to "/" to prevent information disclosure.
https_server	string	If non-null, indicates that the endpoint has https support at the specified URL. Must be of the form `https://host:port` (the port is optional), with no path.
id	string	36 character unique identifier string for the endpoint.
in_use	boolean	"true" if any active tasks owned by the user are using the endpoint.
info_link	string	Link to a web page with more information about the endpoint. ASCII string with an http or https URL. Basic checking is done to make sure this is a valid URL, but the administrator is responsible for running a website at this URL and verifying that it’s accepting public connections.
is_globus_connect	boolean	[DEPRECATED] use `entity_type` instead.
is_go_storage	boolean	[DEPRECATED] Always false.
keywords	string	Comma separated list of search keywords for the endpoint. Optional. Unicode string, max 1024 characters. Searchable.
last_accessed_time	string	Timestamp in ISO 8601 format for the last time this endpoint was accessed. This value is updated once daily by Globus Connect Server v5 and will be null for non Globus Connect Server v5 collections and older versions of Globus Connect Server v5.
local_user_info_available	boolean	Indicates whether the endpoint exposes information about the local user on the endpoint to the Globus service. This is set internally, and can’t be updated. For new endpoints it will start out as null. When a task is run against the endpoint, local user information is requested from the GridFTP server, and if found, this flag will be set to true on the endpoint. If it fails, this will be set to false. Note that there are cases where the server may return a value, but because of the local filesystem and DSI, the value is not particularly useful for searching, but this will still be set to true. On shared endpoints, the value is inherited from the host endpoint.
location	string	"Automatic" or comma separated floats in the form "LATITUDE,LONGITUDE". "null" for shared endpoints.
mapped_collection_display_name	string	The display_name of `mapped_collection_id` if non null.
mapped_collection_id	string	For Globus Connect Server v5 guest collections, the UUID of their mapped collection. For all other endpoint types this will be null.
max_concurrency	integer	Can only be specified if `network_use` is set to "custom", otherwise will contain the preset value for the specified `network_use`. Will be "null" for shared endpoints.
max_parallelism	integer	Can only be specified if `network_use` is set to "custom", otherwise will contain the preset value for the specified `network_use`. Will be "null" for shared endpoints.
mfa_required	boolean	This option indicates that the endpoint requires multi factor authentication for user operations. The endpoint must have `high_assurance` set to true.
my_effective_roles	array of string	List of effective roles the current user has on the endpoint.
myproxy_dn	string	[GCSv4] A non-standard subject DN to use with the default MyProxy server. This is only necessary if the subject DN in the server’s certificate does not match its hostname.
myproxy_server	string	[GCSv4] The default MyProxy server to use when activating this endpoint, or "null" if no associated proxy server.
name	string	[DEPRECATED] Use `display_name` instead.
network_use	string	This field may only be changed on managed endpoints. If a managed endpoint becomes unmanaged, the "normal" level will be automatically used. On shared endpoints, this field will be null. 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; use endpoint-details to display the exact values. "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.
non_functional	boolean	This flag marks an endpoint as not being usable for data access. This flag is not editable and will only be set to true for Globus Connect Server v5 host endpoints.
non_functional_endpoint_display_name	string	The display_name of `non_functional_endpoint_id` if non null.
non_functional_endpoint_id	string	For Globus Connect Server v5 mapped and guest collections, the UUID of their non functional host endpoint. For all other endpoint types this will be null.
oauth_server	string	[GCSv4] hostname of server for getting credentials via oauth. For this to work, the oauth server must be registered with Globus and have the appropriate paths set up. Contact support@globus.org for more information.
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. Searchable.
owner_id	string	Identity id of the endpoint owner/creator. Defaults to your effective_id when created. Can be overridden at creation time to one of your linked identities. Cannot be changed after creation time.
owner_string	string	Identity name of an endpoint administrator. During creation, it will be set to the name of `owner_id`. After creation, it can be changed to any administrator that is set by a user-identity role (and that role may not be deleted). For security, the new administrator must perform the update. Searchable.
preferred_concurrency	integer	Can only be specified if `network_use` is set to "custom", otherwise will contain the preset value for the specified `network_use`. Will be "null" for shared endpoints.
preferred_parallelism	integer	Can only be specified if `network_use` is set to "custom", otherwise will contain the preset value for the specified `network_use`. Will be "null" for shared endpoints.
public	boolean	True if the endpoint definition should be visible to Globus users who don’t have a role on the endpoint.
requester_pays	boolean	Only can be true for Globus Connect Server v5 collections, and cannot be set through the Transfer API. Reflects storage policy options such as `s3_requester_pays` in the S3 Storage Policies Document that indicate costs of using the underlying storage system will be charged to the account of the registered credentials. Note that this is not necessarily the account of the user making Transfer API requests.
s3_owner_activated	boolean	[DEPRECATED] Always "false".
s3_url	null	[DEPRECATED] Always null.
shareable	boolean	[DEPRECATED] use `entity_type` instead.
sharing_target_endpoint	string	[DEPRECATED] use `host_endpoint_id` and `host_endpoint_display_name` instead.
sharing_target_root_path	string	[DEPRECATED] use `host_path` instead.
storage_type	string	[DEPRECATED] Unused.
subscription_id	string	If the endpoint is "managed" under a subscription this will be a UUID string for that subscription, otherwise it will be null. This value can only be set on Globus Connect Server v4 host endpoints and Globus Connect Personal mapped collections using the Transfer API. Globus Connect Server v5 endpoints use the Globus Connect Server Manager API to set their `subscription_id`. Child entities (such as guest collections and shared endpoints) inherit the field from their hosts. If you only manage one subscription id, you can PUT with the special string "DEFAULT" to use that subscription id.
tlsftp_server	string	For Globus Connect Server v5 collections, the url for the tlsftp server used for data access. Will be in the form of "tlsftp://{collection_domain}:{port}". null for other entity types.
user_message	string	A message for clients to display to users when interacting with this endpoint, max length 256 characters. This value can only be set on host endpoints, but will be inherited by shares created off them.
user_message_link	string	Link to additional messaging for clients to display to users when interacting with this endpoint. ASCII string with an http or https URL. Basic checking is done to make sure this is a valid URL, but the administrator is responsible for running a website at this URL and verifying that it’s accepting public connections. This value can only be set on host endpoints, but will be inherited by shares created off them.
username	string	[DEPRECATED] Use `owner_id` and `owner_string` instead.

Note

Some fields have defaults for Endpoints, but their defaults for Collections depend on the settings of the host Endpoint. These fields are as follows:

Field Name	Default behavior
`force_verify`	`false` for Endpoints, but inherits from the host for Mapped and Guest Collections
`disable_verify`	`false` for Endpoints, but inherits from the host for Mapped and Guest Collections

2.2. Server Document

The server document represents a network service that provides access to a filesystem. The most common type is a GridFTP server, which is represented by scheme "gsiftp". This is also the default scheme.

Server Document Example

{
  "DATA_TYPE": "server",
  "id": 985,
  "scheme": "gsiftp",
  "hostname": "gridftp.example.org",
  "port": 2811,
  "subject": "/O=Grid/OU=Example/CN=host/gridftp.example.org"
}

2.2.1. Server Fields

Only hostname is required on create.

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "server" to indicate this document type.
id	int	Unique identifier for a server in an endpoint.
hostname	string	Hostname of the server.
port	int	Port the server is listening on. Default: 2811.
scheme	string	URI scheme (protocol) used by the endpoint. Must be "gsiftp" or "ftp". Default: "gsiftp".
subject	string	subject of the x509 certificate of the server. If not specified, the CN in the subject must match its hostname.
incoming_data_port_start	int	Start (inclusive) of port range allowed for incoming GridFTP data connections. The purpose of this field is to indicate to firewall administrators at other sites how to allow traffic between this endpoint and their own endpoints. If "null", indicates that the endpoint administrator has not specified the configuration (the allowed range is unknown). A range of 1024-65535 indicates a completely open configuration. Must be a subset of 1024-65535 (privileged ports below 1024 are not allowed by GridFTP). Must be set along with `incoming_data_port_end`, i.e. both must be set to a valid value, or both must be set to "null". Can only be set on GridFTP endpoints.
incoming_data_port_end	int	End (inclusive) of port range allowed for incoming data connections. Must be greater or equal to `incoming_data_port_range_start`.
outgoing_data_port_start	int	Like `incoming_data_port_start` but for outgoing data connections.
outgoing_data_port_end	int	Like `incoming_data_port_end` but for outgoing data connections.
uri	string	[DEPRECATED] URI of the server. This is a derived field combining the scheme, hostname, and port, and is not used when creating servers.
is_connected	boolean	[DEPRECATED] Use `gcp_connected` in the `endpoint` document instead. For globus connect personal endpoints, indicates if the endpoint is available for operations; always true for other endpoints. When false, check the value of `is_paused` to determine if the user requested a temporary disconnect, or if globus connect is not running or not connected to a network.
is_paused	boolean	[DEPRECATED] Use `gcp_paused` in the `endpoint` document instead. For globus connect endpoints, indicates if the endpoint has been paused by the user. Note that when this is true, is_connected will always be false, because the endpoint is not available for any operations when paused. For non globus connect endpoints, `is_paused` will always be false.

2.3. Shared Endpoint Document

The shared endpoint document is a subtype of the "endpoint" document used to create shared endpoints only. Once created, a shared endpoint is accessed and updated using the standard endpoint resources.

server documents can’t be added or removed from shared endpoints; the server used depends entirely on the host endpoint.

Note

Use host_endpoint to create a shared endpoint, but use host_endpoint_id to look up a shared endpoint or to distinguish it from other types of endpoints.

Shared Endpoint Document Example

{
  "DATA_TYPE": "shared_endpoint",
  "display_name": "myshare",
  "host_endpoint": "2ebc7b58-de6f-46a3-ac36-2f2613aa32ba",
  "host_path": "/~/",
  "description": "Share my home directory on Globus Tutorial Endpoint 1",
  "organization": "my org"
}

The "shared_endpoint" document can include other informational fields like contact_email and keywords, and option fields like force_encryption (see the updatable field list and full endpoint field list for details). Note that shared endpoints are always public, and the location and network_use related fields are inherited from the host and not settable. The identity provider related fields, myproxy_server and oauth_server, can’t be set on shared endpoints, because they are authenticated using Globus credentials.

3. Path Arguments

Name	Type	Description
endpoint_xid	string	The `id` field of the endpoint, or for backward compatibility the `canonical_name` of the endpoint. The latter is deprecated, and all clients should be updated to use `id`.

4. Common Query Parameters

Name	Type	Description
fields	string	Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed.

5. Common Errors

The error code can be found in the HTTP response body JSON document. See error overview .

Code	HTTP Status	Description
EndpointNotFound	404	If <endpoint_xid> not found
PermissionDenied	403	If user does not have privileges to get, modify, or delete the specified endpoint(s).
EndpointDeleted	409	See Get endpoint by id. The error document contains a `deleted_time` field indicating when the endpoint was deleted, in addition to the standard error fields.
ClientError.Conflict	409	If an endpoint with the same name already exists or if a role assignment with the same principal and role already exists.
ServiceUnavailable	503	If the service is down for maintenance.

6. Operations

6.1. Get endpoint by id

Get a single endpoint by id. All fields are included by default, including the server subdocuments, but the fields query parameter can be used to fetch only specific fields. Use "server" in the fields list to include server subdocuments in a limited field list. For backward compatibility, an endpoint canonical_name can be specified instead of the endpoint id, but this feature is deprecated and all clients should migrate to using the id.

Note

Returns an "EndpointDeleted" error instead of "EndpointNotFound" for deleted endpoints, but only when using id in the URL <endpoint_xid> argument. If an endpoint canonical_name is used for the <endpoint_xid>, it will return "EndpointNotFound" for deleted endpoints.

Authorization

Requires that the endpoint is public or that the user has an "administrator" "restricted_administrator" or "activity_monitor" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>
Method	GET
Response Body	Endpoint document

6.2. Create endpoint

Create an endpoint. Which fields are required depends on the type of endpoint. Note that name and canonical_name are deprecated and supported only for backward compatibility; display_name should be used instead of, or in addition to, these fields. If canonical_name is not set, it will default to "USERNAME#ENDPOINT_UUID". At least one of them must be specified.

The result will include an id field containing the globally unique endpoint id, which should be used to further manipulate the endpoint document, and to perform transfers and other operations on the endpoint’s filesystem.

Globus Connect Server endpoints

At least one of display_name and canonical_name is required, but at least one "server" sub document must be created for it to function.

Globus Connect Personal endpoints

Requires display_name or canonical_name, and is_globus_connect must be set to "true". Once created, the setup key can be obtained from the endpoint document in field globus_connect_setup_key.

Shared endpoints

Shared endpoints are created using a different resource, see Create shared endpoint.

URL	/endpoint
Method	POST
Request Body	Endpoint document
Response Body	Result document, including an `id` field containing the system generated id of the new endpoint.

6.3. Create shared endpoint

Create a shared endpoint.

Authorization

Requires that the host endpoint is managed. For Globus Connect Personal endpoints, creating a shared endpoint is only allowed for the owner of the host endpoint.

Note

If the authorization requirement is no longer met in the future, e.g. if the endpoint is made unmanaged, task submission will not be allowed. In this case, attempting to submit a new task will result in a "NotLicensedException" error.

URL	/shared_endpoint
Method	POST
Request Body	Shared endpoint document
Response Body	Result document, including an `id` field containing the system generated id of the new endpoint.

6.4. Update endpoint by id

Update an endpoint. This can be done using a partial document by specifying only DATA_TYPE and the fields to be updated, or doing a GET on the endpoint, changing the appropriate fields, and doing a PUT of the full document. Using a partial document is preferred.

Note

Endpoint PUT can not be used to update the servers on the endpoint. The server APIs should be used instead. New code should not pass a "DATA" key at all when doing endpoint update.

Authorization

Requires an "administrator" or "restricted_administrator" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>
Method	PUT
Request Body	Partial endpoint document
Response Body	Result document

Which fields can be updated depends on the type of endpoint:

Type	Updatable fields
All Endpoint Types	`display_name`, `description`, `organization`, `department`, `keywords`, `contact_email`, `contact_info`, `info_link`, `owner_string` `force_encryption`, `disable_verify` DEPRECATED: `name`, `canonical_name`
Globus Connect Server	`subscription_id`, `public` `location`, `network_use`, `max_concurrency`, `preferred_concurrency`, `max_parallelism`, `preferred_parallelism` `myproxy_server`, `myproxy_dn`, `oauth_server`
Globus Connect Personal	`subscription_id`, `public` `location`, `network_use`, `max_concurrency`, `preferred_concurrency`, `max_parallelism`, `preferred_parallelism`, `default_directory`
Shared endpoint	`https_server`

6.5. Delete endpoint by id

Delete an endpoint by id or canonical name (the latter is deprecated). Note that all data associated with the endpoint, including roles and the ACL, will be deleted as well. If the hostname of the server has changed, the server document(s) in the endpoint should be changed rather than deleting and recreating the endpoint with different servers.

Authorization

Requires an "administrator" or "restricted_administrator" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>
Method	DELETE
Response Body	Result document

6.6. Get my effective endpoint pause rules

Get all pause rules on an endpoint that affect the current user, with sensitive administrator only fields removed.

URL	/endpoint/<endpoint_xid>/my_effective_pause_rule_list
Method	GET
Response Body	List of "pause_rule_limited" documents

6.7. Get endpoint server list

Get a list of all servers belonging to the specified endpoint. Note that this is the same as the server list included under the "DATA" key of the endpoint document.

Authorization

Requires that the endpoint is public or that the user has an "administrator" "restricted_administrator" or "activity_monitor" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>/server_list
Method	GET
Response Body	List of server documents

6.8. Get endpoint server by id

Get a specific server belonging to the specified endpoint.

Authorization

Requires that the endpoint is public or that the user has an "administrator" "restricted_administrator" or "activity_monitor" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>/server/<server_id>
Method	GET
Response Body	A "server" document

6.9. Add endpoint server

Add a server to the specified endpoint. The hostname field is required, scheme and port default to "gsiftp" and 2811, and subject defaults to "null". The derived fields and boolean status fields are ignored, and should not be included in the request body.

Returns a result document containing the id of the newly added server.

Authorization

Requires the "administrator" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>/server
Method	POST
Response Body	Server document without the id.
Response Body	`{ "DATA_TYPE": "endpoint_server_add_result", "id": 123, "code": "Created", "message": "Server added to endpoint successfully", "resource": "/endpoint/347a942d-3bf6-4d43-98e0-16e29cfb1d82/server", "request_id": "ABCdef789" }`

6.10. Update endpoint server by id

Update a server belonging to the specified endpoint. Include only the fields to be updated in the request body - any of hostname, scheme, port, and subject can be updated.

Authorization

Requires the "administrator" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>/server/<server_id>
Method	PUT
Request Body	Partial server document.
Response Body	Result document

6.11. Delete endpoint server by id

Delete a server belonging to the specified endpoint.

Authorization

Requires the "administrator" effective role on the endpoint.

URL	/endpoint/<endpoint_xid>/server/<server_id>
Method	DELETE
Response Body	Result document

6.12. Get my shared endpoint list

Get a list of shared endpoints for which the user has an "administrator", or "access_manager" effective role. hosted by a given GridFTP or Globus Connect Personal endpoint.

Returns a "BadRequest" error if called on an endpoint that can’t host shared endpoints.

This resource uses offset paging, and includes a has_next_page boolean in the response body.

Authorization

Same as get endpoint by ID (GET /endpoint/<endpoint_xid>).

URL	/endpoint/<endpoint_xid>/my_shared_endpoint_list
Method	GET
Response Body	An "endpoint_list" document

6.12.1. Query Parameters

Query Parameter	Type	Default	Description
limit	int	1000	Maximum number of results to return. 1000 is both the default and maximum.
offset	int	0	Return results starting from this offset within the total result set.

6.13. Get shared endpoint list

Get all shared endpoints hosted by a specific host endpoint. Currently, only the endpoint id attribute is returned.

This resource uses next token paging. By default, the limit is 1000 results per API call. The query parameter max_results can override this; it must be >= 1 and <= 1000.

Authorization

Same as get endpoint by ID (GET /endpoint/<endpoint_xid>).

URL	/endpoint/<endpoint_xid>/shared_endpoint_list?[next_token=TOKEN][max_results=MAX_RESULTS]
Method	GET
Response Body	{ "next_token": <null or string> "shared_endpoints": [ { "id": <string> }, ... ] }