Skip to content

Credentials Service

An ARD service for registering Azure or Google cloud platform credentials and generating a credentials ID. You must be an account administrator to register credentials.

Last updated: June 15, 2022

You can register credentials from the Maxar ARD Dashboard User Interface (RECOMMENDED)

Read the ARD Dashboard Credentials Management help topic

Overview

The Maxar ARD Credentials Service allows account administrators to register credentials that give access to deliver output data to an Azure Blob Storage container or a Google Cloud Platform bucket. Registering credentials generates a credentials ID that can be shared among the users of the account. The credentials ID is used to configure the delivery location in an ARD order request.

Registering credentials is not required. Credentials can be submitted each time an order is placed. We recommend registering a set of credentials for your account for the following reasons:

  • If your credentials are long-lived, with an expiration date far in the future, you only need to register them once.

  • You can create a credentials ID that's easy to remember and distribute it to everyone in your account to use.

  • A new set of credentials can be updated for a credentials ID. This means users in your account can continue using the same credentials ID for order requests even if the credentials are updated.

  • Credentials can be deactivated and reactivated to revoke and reinstate Maxar's access to your storage location.

Credentials for cloud platforms

cloud platform credential type
Amazon S3 credentials are set up by S3 bucket policy, and are not registered in the Credentials Service
Azure Blob Storage Signed Access Signature (SAS) URL. A long-lived SAS is recommended.
Google Cloud Platform The base64-encoded string of the JSON credentials document.

Registering and sharing credentials

1. Make A PUT request to the Credentials API endpoint.

You'll set a credentials ID as a path parameter and submit the credentials with a description in the request body.

The credentials ID should be something easy to remember. You'll pass it to the other users in the account to use when placing an order, and you'll use it to update your credentials if needed. It can be something as simple as "our_shared_creds." If you'll be registering different credentials for different buckets or containers, you could incude a bucket name or project name to differentiate the credentials.

For our example, we'll use "ard_demo_creds" as the credentials ID.

The registration endpoint is:

/admin/account/{account_id}/credentials/{credentials_id}

Example registration request:

/admin/account/5580636127.../credentials/ard_demo_creds

{
    "credentials": "credentials URL goes here",
    "description": "use for orders placed for demo purposes"
}

Example response:

{
    "registered_credentials": {
        "credentials_id": "ard-demo-creds",
        "account_id": "5580636127253...",
        "description": "use for orders placed for demo purposes",
        "created": "2021-01-30T00:27:47.971028Z",
        "modified": "2021-01-30T00:27:47.971105Z"
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/admin/account/55806361272538.../credentials/our-shared-creds",
        "account": "https://ard.maxar.com/api/v1/admin/account/558063612725..."
    },
    "response_timestamp": "2021-02-01T01:23:45Z"
}

2. Distribute the credentials_id to other users in the account.

Example: Account Administrator sends this information to the users in your account. They will add this to the output_config section of any order request they place.

"credentials_id": "ard_demo_creds"

3. Add the credentials_id to the output_config section of an order request (any user within the account).

Example: Order request with credentials_id

{
    "select_id": "[the ID from your imagery selection response]",
    "output_config": {
        "azure_blob_storage": {
            "credentials_id": "ard_demo_creds",
            "container": "ard_demo_azure_container",
            "prefix":"prefix/directory order should be delivered to"
        }
    },
    "notifications": [
        {
            "type": "email",
            "address": "valid_email@email.com"
        }
    ]
}

Updating registered credentials

The information registered with a credentials_id can be updated. The credentials_id does not change in an update request. When credentials are updated:

  • In-progress orders that were submitted before the credentials were updated will complete successfully.

  • Users in the account will continue to submit orders using the same credentials_id.

Credentials can be updated using one of the two following methods:

  • The PUT method updates the full set of credentials. With this method, all fields must be included in the request. When using this method to update an existing record, the credentials_id for the record being updated is added to the path.

  • The PATCH method updates a partial record. With this method, only the field to be updated is included in the request body. For example, if the Azure Blob Storage SAS url should be updated but the description will not change, the request body would include only the credentials field.

Updating/replacing all data associated with a credentials_id

Use the PUT method to update all data associated with an existing credentials_id.

PUT /admin/account/{account_id}/credentials/{credentials_id}

Example: updating a record that was previously registered.

For this example, we're updating the data associated with the credentials_id we created above, ard-demo creds.

PUT /admin/account/5580636127253/credentials/ard_demo_creds

Example request body

{
    "credentials": "[new SAS URL].",
    "description": "Updated description for these credentials"
}

Update part of the data associated with a credentials_id

Use the PATCH method to update only part of the credentials record.The credentials_id is included in the path.

PATCH /admin/account/5580636127253/credentials/ard_demo_creds

Example request body:

In this example, only the credentials field will be updated.

{
    "credentials": "[new SAS URL].",
}

List all credentials

An ARD account can have more than one set of registered credentials. Use this request to list all credentials associated with the account. For security, the value for the credentials is not displayed in the response.

GET /admin/account/{account_id}/credentials

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

{
    "data": [
        {
            "registered_credentials": {
                "credentials_id": "ard-demo-creds",
                "account_id": "5568860438...",
                "description": "credentials for ordering data for demos",
                "created": "2021-05-18T16:29:09Z",
                "modified": "2021-05-18T16:32:19Z"
            },
            "links": {
                "self": "https://ard.maxar.com/api/v1/admin/account/556886043/credentials/ard-demo-creds",
                "account": "https://ard.maxar.com/api/v1/admin/account/5568860438844188876"
            },
            "response_timestamp": "2021-06-22T18:43:11Z"
        },
        {
            "registered_credentials": {
                "credentials_id": "our-shared-credentials",
                "account_id": "55688604388...",
                "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/55688604388.../credentials/our-shared-credentials",
                "account": "https://ard.maxar.com/api/v1/admin/account/5568860438..."
            },
            "response_timestamp": "2021-06-22T18:43:11Z"
        }
    ],
    "has_more": false,
    "object": "list",
    "url": "https://ard.maxar.com/api/v1/admin/account/5568860438.../credentials"
}

Get information for a set of credentials

To see information about a set of credentials, send a GET request with the account_id and the credentials_id in the path. For security, the value for the credentials field is not displayed in the response.

GET /admin/account/{account_id}/credentials/{credentials_id}

Response example:

  {
    "registered_credentials": {
        "credentials_id": "ard-demo-creds",
        "account_id": "558063612725",
        "description": "Description of the credentials.",
        "created": "2021-01-30T00:27:47.971028Z",
        "modified": "2021-01-30T00:27:47.971105Z"
    },
    "links": {
        "self": "https://ard.maxar.com/admin/account/5580636127253839282/credentials/our-shared-creds",
        "account": "https://ard.maxar.com/api/v1/admin/account/5580636127253839282"
    },
    "response_timestamp": "2021-02-01T01:23:45Z"
}

Deleting credentials

Deleting credentials from the ARD Credentials service will revoke Maxar's access to your storage location. If a set of credentials is deleted from the ARD credentials service, any new order that uses the deleted credentials will fail.

DEL https://ard.maxar.com/admin/api/v1/account/:account_id/credentials/{credentials_id}
Back to top