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}
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"
}
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}
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}
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"
}
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
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.