User Credentials

The User Credential API allows users to manage credentials needed to access storage gateways. The credentials may take different forms, based on the connector being used.

Overview

Method	API Path	Description
`POST`	/user_credentials	Create User Credential
`GET`	/user_credentials	Get User Credentials

Overview

Method	API Path	Description
`GET`	/user_credentials/{user_credential_id}	Get User Credential
`PATCH`	/user_credentials/{user_credential_id}	Update a User Credential
`PUT`	/user_credentials/{user_credential_id}	Update a User Credential
`DELETE`	/user_credentials/{user_credential_id}	Delete a User Credential

Common Path Parameters

Parameter	Type	Description
user_credential_id (required)	string Any	ID of the User Credential

Details

Create User Credential

POST /user_credentials

Create a user credential on a Storage Gateway. When accessing data for most connectors, this API call is not needed, as the credential will be created on first login. However, some do require additional data. When that is the case, transfer or HTTPS access to the data on the collection will fail with an invalid_credential#1.0.0 error. You can avoid that by posting credentials with this API prior to logging in the first time.

See the connector-specific documentation for the fields on the UserCredential document that may be provided on credential creation.

The caller is authorized based on the StorageGateway identity policies, so users with no assigned roles on the endpoint may be permitted to access this operation.

Authorization

StorageGatewayAuthorizer [ {storage_gateway_id} ]

Request body

application/json

Credential information for an identity on a particular Storage Gateway and its related collections.

Name	Type	Description
DATA_TYPE	string `user_credential#1.0.0`	Type of this document
id	string <uuid>	Unique id string for this User Credential
identity_id	string <uuid>	Globus Auth identity id that this credential is associated with.
connector_id	string <uuid>	Connector that this credential is used with.
username	string	Connector-specific username that this credential is associated with. If the connector supports identity mapping, this matches the result of the mapping applied to identity_id.
display_name	string	Display name of the credential.
storage_gateway_id	string	Storage Gateway this credential is associated with.
invalid	boolean	Flag indicating that this credential is no longer valid.
provisioned	boolean	Flag indicating that this credential has been fully provisioned. If this is false and the invalid property is true, then the credential was created during login and patching it to add the missing data should be presented to the user as initializing the credential.
policies	One of { BlackPearlUserCredentialPolicies , object BoxUserCredentialPolicies , object CephUserCredentialPolicies , object GoogleDriveUserCredentialPolicies , GoogleCloudStorageUserCredentialPolicies , IrodsUserCredentialPolicies , PosixUserCredentialPolicies , PosixStagingUserCredentialPolicies , object S3UserCredential , object }	Connector-specific user credential policies.

Example

{
  "DATA_TYPE": "user_credential#1.0.0",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "identity_id": "c8b7ab5c-595c-43c9-8e43-9e8a3debfe4c",
  "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
  "username": "testuser",
  "display_name": "Test User",
  "storage_gateway_id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
  "home_directory": "/home/user",
  "invalid": true,
  "provisioned": true,
  "policies": {
    "DATA_TYPE": "blackpearl_user_credential_policies#1.0.0",
    "access_id": "amFzb25hbHQ=",
    "secret_key": "K9YxrEaj"
  }
}

Responses

200 - Create User Credential result

Table 1. application/json
Name	Type	Description
code	string `success`
data	array (object) ( UserCredential )
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": "user_credential#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "identity_id": "c8b7ab5c-595c-43c9-8e43-9e8a3debfe4c",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "username": "testuser",
      "display_name": "Test User",
      "storage_gateway_id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "home_directory": "/home/user",
      "invalid": true,
      "provisioned": true,
      "policies": {
        "DATA_TYPE": "blackpearl_user_credential_policies#1.0.0",
        "access_id": "amFzb25hbHQ=",
        "secret_key": "K9YxrEaj"
      }
    }
  ],
  "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 - Forbidden

Table 2. application/json
Name	Type	Description
code	string `permission_denied`
http_response_code	`403`
detail	One of { object MissingRequiredRole , object NotResourceOwner , object NotFromAllowedDomain , AuthenticationTimeout , object IdNotInIdentitySet }
DATA_TYPE	string `result#1.0.0`	Type of this document.
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": "permission_denied",
  "http_response_code": 403,
  "detail": {
    "DATA_TYPE": "missing_required_role#1.0.0",
    "roles": [
      {
        "role": "administrator",
        "collection": "18d367d5-45cf-4724-a53e-5a685e45c942"
      }
    ]
  },
  "DATA_TYPE": "result#1.0.0",
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}

Get User Credentials

GET /user_credentials

Get an array of User Credentials.

Authorization

PublicAuthorizer
StorageGatewayAuthorizer [ {storage_gateway_id} ]

Query Parameters

Parameter	Type	Description
storage_gateway	string Any	ID of the Storage Gateway.
marker	string Any	Pagination marker for a paginated response

Responses

200 - Get User Credentials

Table 3. application/json
Name	Type	Description
code	string `success`
data	array (object) ( UserCredential )
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": "user_credential#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "identity_id": "c8b7ab5c-595c-43c9-8e43-9e8a3debfe4c",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "username": "testuser",
      "display_name": "Test User",
      "storage_gateway_id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "home_directory": "/home/user",
      "invalid": true,
      "provisioned": true,
      "policies": {
        "DATA_TYPE": "blackpearl_user_credential_policies#1.0.0",
        "access_id": "amFzb25hbHQ=",
        "secret_key": "K9YxrEaj"
      }
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

Details

Get User Credential

GET /user_credentials/{user_credential_id}

Get a User Credential by its id.

The caller must have the identity_id of the user credential in its identity set.

Authorization

UserCredentialOwnerAuthorizer [ {user_credential_id} ]

Responses

200 - Get User Credential Response

Table 4. application/json
Name	Type	Description
code	string `success`
data	array (object) ( UserCredential )
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": "user_credential#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "identity_id": "c8b7ab5c-595c-43c9-8e43-9e8a3debfe4c",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "username": "testuser",
      "display_name": "Test User",
      "storage_gateway_id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "home_directory": "/home/user",
      "invalid": true,
      "provisioned": true,
      "policies": {
        "DATA_TYPE": "blackpearl_user_credential_policies#1.0.0",
        "access_id": "amFzb25hbHQ=",
        "secret_key": "K9YxrEaj"
      }
    }
  ],
  "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 - Forbidden

Table 5. application/json
Name	Type	Description
code	string `permission_denied`
http_response_code	`403`
detail	NotResourceOwner	Error details when a user has authenticated but is not the owner of the resource being acted upon.
DATA_TYPE	string `result#1.0.0`	Type of this document.
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": "permission_denied",
  "http_response_code": 403,
  "detail": {
    "DATA_TYPE": "not_resource_owner#1.0.0",
    "id": "d65768d9-f00a-4921-93be-a16c8f20200d"
  },
  "DATA_TYPE": "result#1.0.0",
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}

404 - Not Found

Update a User Credential

PATCH /user_credentials/{user_credential_id}

Update a User Credential document, changing only the properties included in the input document.

Authorization

UserCredentialOwnerAuthorizer [ {user_credential_id} ]

Responses

200 - Patch User Credential Response

Table 6. application/json
Name	Type	Description
code	string `success`
data	array (object) ( UserCredential )
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": "user_credential#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "identity_id": "c8b7ab5c-595c-43c9-8e43-9e8a3debfe4c",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "username": "testuser",
      "display_name": "Test User",
      "storage_gateway_id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "home_directory": "/home/user",
      "invalid": true,
      "provisioned": true,
      "policies": {
        "DATA_TYPE": "blackpearl_user_credential_policies#1.0.0",
        "access_id": "amFzb25hbHQ=",
        "secret_key": "K9YxrEaj"
      }
    }
  ],
  "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 - Forbidden

Table 7. application/json
Name	Type	Description
code	string `permission_denied`
http_response_code	`403`
detail	NotResourceOwner	Error details when a user has authenticated but is not the owner of the resource being acted upon.
DATA_TYPE	string `result#1.0.0`	Type of this document.
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": "permission_denied",
  "http_response_code": 403,
  "detail": {
    "DATA_TYPE": "not_resource_owner#1.0.0",
    "id": "d65768d9-f00a-4921-93be-a16c8f20200d"
  },
  "DATA_TYPE": "result#1.0.0",
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}

404 - Not Found

Update a User Credential

PUT /user_credentials/{user_credential_id}

Update a User Credential document, replacing the entire User Credential with the input document.

Authorization

UserCredentialOwnerAuthorizer [ {user_credential_id} ]

Responses

200 - Put User Credential Response

Table 8. application/json
Name	Type	Description
code	string `success`
data	array (object) ( UserCredential )
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": "user_credential#1.0.0",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "identity_id": "c8b7ab5c-595c-43c9-8e43-9e8a3debfe4c",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "username": "testuser",
      "display_name": "Test User",
      "storage_gateway_id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "home_directory": "/home/user",
      "invalid": true,
      "provisioned": true,
      "policies": {
        "DATA_TYPE": "blackpearl_user_credential_policies#1.0.0",
        "access_id": "amFzb25hbHQ=",
        "secret_key": "K9YxrEaj"
      }
    }
  ],
  "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 - Forbidden

Table 9. application/json
Name	Type	Description
code	string `permission_denied`
http_response_code	`403`
detail	NotResourceOwner	Error details when a user has authenticated but is not the owner of the resource being acted upon.
DATA_TYPE	string `result#1.0.0`	Type of this document.
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": "permission_denied",
  "http_response_code": 403,
  "detail": {
    "DATA_TYPE": "not_resource_owner#1.0.0",
    "id": "d65768d9-f00a-4921-93be-a16c8f20200d"
  },
  "DATA_TYPE": "result#1.0.0",
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}

404 - Not Found

Delete a User Credential

DELETE /user_credentials/{user_credential_id}

Delete a User Credential by its id.

This may fail with a Conflict error if any Guest Collections exist which use this credential.

The caller must have the identity_id of the user credential in its identity set.

Authorization

UserCredentialOwnerAuthorizer [ {user_credential_id} ]

Responses

200 - Delete User Credential result

Table 10. 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 - Forbidden

Table 11. application/json
Name	Type	Description
code	string `permission_denied`
http_response_code	`403`
detail	NotResourceOwner	Error details when a user has authenticated but is not the owner of the resource being acted upon.
DATA_TYPE	string `result#1.0.0`	Type of this document.
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": "permission_denied",
  "http_response_code": 403,
  "detail": {
    "DATA_TYPE": "not_resource_owner#1.0.0",
    "id": "d65768d9-f00a-4921-93be-a16c8f20200d"
  },
  "DATA_TYPE": "result#1.0.0",
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}