Skip to content

Credentials Resource

Last updated: August 29, 2022


Credentials

/admin/account/credentials

See also Credentials Service Guide

Register credentials for the Microsoft Azure or Google cloud platforms.

http method path description role required
PUT /admin/account/{account_id}/credentials Register or update credentials and get a credentials ID. Admin
PATCH /admin/account/{account_id}/credentials/{credentials_id} Update part of a credentials record. Admin
GET /admin/account/{account_id}/credentials Get a list of credentials registered for the account. Admin
GET /admin/account/{account_id}/credentials/{credentials_id} Get credentials information. Admin
DEL /admin/account/{account_id}/credentials/{credentials_id} Delete a set of credentials. Admin

Headers

key value description
Authorization Bearer {{token}} Authentication method for ARD API requests.
Content-Type application/json Applies to POST, PATCH, PUT requests, which require a JSON body.

Register new credentials or update a full set of credentials

PUT /admin/account/{account_id}/credentials/{credentials_id}
Role required: Admin

Register credentials for the Azure or Google cloud platforms. The PUT method creates a new credentials record or completely replaces an existing matching record. Values must be supplied for all required fields.

Note: If you use the AWS S3 cloud platform, you'll set a bucket policy that provides write access to your s3 bucket instead of storing credentials.

This PUT request is used for the following:

  • Register a new set of credentials.

  • Replace a full set of credentials, using an existing credentials ID. Values must be supplied for all required fields

Path Parameters

param description example
credentials_id The name given to the credentials. our-shared-creds

Request Body

param desription example
credentials A value which will be stored for the credentials. For Google Cloud Storage, the value must be the base64-encoded string of the JSON credentials document. For Microsoft Azure blob storage, the value must be a long-lived SAS URL (the shorter the expiration time, the more frequently the credentials will need to be updated). "credentials": "https://[dependent on platform}]"
description A useful description that helps identify the credentials or the purpose of the credentials. "description": "useful description of the credentials."

Registering new credentials

Add a new credentials_id to the path when registering a set of credentials for the first time. This is a string and should be a value that's easy to remember. The credentials_id can include alphanumeric characters, hyphens, or underscores; but won't accept other characters. This ID will be passed by the admin to other members of the account for use when ordering ARD imagery.

Example:

PUT /admin/account/{account_id}/credentials/our-shared-creds

Note: If you use the AWS S3 cloud platform, you'll set a bucket policy that provides write access to your s3 bucket instead of storing credentials.

When replacing an existing full set of credentials with a PUT request, add the existing credentials ID to the path and update the body parameters.

Request Body

{
 "credentials": "credentials URL goes here",
 "description": "useful description of the credentials."
}

Response

Example

Status: 201 Created

 {
    "registered_credentials": {
        "credentials_id": "our-shared-creds",
        "account_id": "557471230760500000",
        "description": "useful description of the credentials.",
        "created": "2021-01-30T00:27:47.971028Z",
        "modified": "2021-01-30T00:27:47.971105Z"
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/admin/account/557471230760500000/credentials/our-shared-creds",
        "account": "https://ard.maxar.com/api/v1/admin/account/557471230760500000"
    },
    "response_timestamp": "2021-07-01T01:23:45Z"
}
Note: the credentials are never returned as part of the response; however, they are stored encrypted as part of the records for your account.

Response fields
field description example
registered credentials The credentials object displays credentials ID, account ID, description, date created, and date modified. See example fields in this table.
credentials_id The credentials ID registered for the set of credentials. "credentials_id": "our-shared-creds"
account_id The ID for the account the credentials are registered under. "account_id": "9999636127253830000"
description A useful description of the credentials to help identify them. "description":"credentials for demo purposes."
created The date the credentials were registered. "created": "2021-01-30T00:27:47.971028Z"
modified The last modified date for the credentials. If no updates have been made since the credentials were registered, the "created" and "modified" dates will be the same. "modified": "2021-01-30T00:27:47.971105Z"
links Links to additional information about the account or user. Links require ARD authentication. See examples below in this table.
self Get details about the credentials "self": "https://ard.maxar.com/api/v1/admin/account/557471230760500000/credentials/our-shared-creds"
account Get details about the account the credentials are registered under. "account": "https://ard.maxar.com/api/v1/admin/account/557471230760500000"
response_timestamp The date and time of the response to the credentials request. "response_timestamp": "2021-07-01T01:23:45Z

Update part of a credentials record

PATCH /admin/account/{account_id}/credentials/{credentials_id}
Update the credentials URL or the description for a credentials ID.

Role: Admin

Path Parameters

param description example
account_id The ID for the account where the credentials will be registered. 557471230760500000
credentials_id The name given to the credentials. our-shared-creds

Request body

Include only the field or fields that needs to be updated in the request body.

Example: Update the description for existing credentials.

  {
     "description": "use for orders for Customer XYZ only"
  }

Response

Status: 200 OK

See response to the PUT credentials request.

List credentials stored for the account

GET admin/account/:account_id/credentials/

Returns a list of credentials registered to the account.

Role: admin

Path Parameters

param description example
account_id The ID for the account where the credentials will be registered. 557471230760500000

Query parameters

Pagination

If has_more in the response is true, you can request the next set of records by appending the ?ending_before=<id> parameter to the request url. For the id, use the credentials_id of the last credential object listed in the response. For example, if the response above indicated there were more records to request, you would request the next page using: `GET admin/account/:account_id/credentials/?ending_before=our-shared-credentials

Response

Status: 200 OK

Example response with two sets of credentials registered for the account.

{
    "data": [{
            "registered_credentials": {
                "credentials_id": "ard-demo-creds",
                "account_id": "557471230760500000",
                "description": "credentials for ordering data for demos",
                "created": "2021-05-18T16:29:09Z",
                "modified": "2021-07-18T16:32:19Z"
            },
            "links": {
                "self": "https://ard.maxar.com/api/v1/admin/account/557471230760500000/credentials/ard-demo-creds",
                "account": "https://ard.maxar.com/api/v1/admin/account/557471230760500000"
            },
            "response_timestamp": "2021-06-22T18:43:11Z"
        },
        {
            "registered_credentials": {
                "credentials_id": "our-shared-credentials",
                "account_id": "557471230760500000",
                "description": "credentials shared with the team",
                "created": "2021-06-10T13:50:08Z",
                "modified": "2021-06-10T13:51:49Z"
            },
            "links": {
                "self": "https://ard.maxar.com/api/v1/admin/account/557471230760500000/credentials/our-shared-credentials",
                "account": "https://ard.maxar.com/api/v1/admin/account/557471230760500000"
            },
            "response_timestamp": "2021-06-22T18:43:11Z"
        }
    ],
    "has_more": false,
    "object": "list",
    "url": "https://ard.maxar.com/api/v1/admin/account/557471230760500000/credentials"
}

The has_more field indicates whether there are more records which would be returned by requesting another page.

Get credentials

Returns information about registered credentials, based on the credentials_id. For security, the value for the credentials field is not displayed in the response.

GET /admin/account/{account_id}/credentials/{credentials_id}
Role: Admin

Path parameters

param description example
account_id The ID for the account where the credentials will be registered. 557471230760500000
credentials_id The name given to the credentials. our-shared-creds

Response

Status: 200 OK

{
  "registered_credentials": {
    "credentials_id": "our-shared-creds",
    "account_id": "557471230760500000",
    "description": "Meaningful description to help identify credentials",
    "created": "2021-01-30T00:27:47.971028Z",
    "modified": "2021-01-30T00:27:47.971105Z"
  },
  "links": {
    "self": "https://ard.geobigdata.io/admin/account/557471230760500000/credentials/our-shared-creds",
    "account": "https://ard.maxar.com/api/v1/admin/account/557471230760500000"
  },
  "response_timestamp": "2021-07-01T01:23:45Z"
}
See response to a PUT credentials request for field descriptions.

Delete credentials

Description: Deletes a set of credentials from the credentials service.

Role: Admin

Path parameters

param description example
account_id The ID for the account where the credentials will be registered. 557471230760500000
credentials_id The name given to the credentials. our-shared-creds

DEL https://ard.maxar.com/admin/api/v1/account/557471230760500000/credentials/our-shared-creds
Orders placed before the credentials were deleted will complete. New order requests placed using a credentials ID that has been deleted will return an error.

Response codes

A successful DELETE request results in a 204 no content message.

If the credentials cannot be deleted because the account ID or credentials ID can't be found, a 404 Bad Request response is returned.

More Documentation

Credentials Service Guide

Back to top