Account Administration API Guide¶

Last updated: January 20, 2023¶

Overview¶

Looking for the Administrative Tools User Interface? Go here (RECOMMENDED)

Account administrators are responsible for inviting and managing users to an account. Additional account administrator responsibilities are explained in this document.

Account and User Administration can be managed by a set of API requests. You can use the ARD Postman Collection to submit your requests.

See Account API Reference for request details.

Root URL¶

The account administration endpoint is part of the ARD API. The root URL for the API is:

https://ard.maxar.com/api/v1

When a request URL is shown in this tutorial, the root URL must be appended to the front. For example:

https://ard.maxar.com/api/v1/admin/account/{account_id}/user

Account Management¶

Accounts are created and updated by the Maxar ARD Support team. All accounts have a user that is an account administrator, or admin. The admin has the ability to get the details of the account, list the orders placed under their account, and manage users.

Get the details of an account¶

The account administrator can make a request to get the details set for the account. see Accounts API Reference for more informaiton.

To learn more about account usage data, see Usage Guide.

Example response:

Status; 200 OK

{
    "account": {
        "account_id": "5600098189427357..",
        "name": "Maxar ARD Docs",
        "sap": "65432",
        "contract_start": "2022-02-20",
        "contract_end": "2023-02-20",
        "active": true,
        "internal": false,
        "sales_support_contacts": null,
        "created": "2021-02-25T20:55:26Z",
        "modified": "2022-06-03T15:13:41Z",
        "pricing": {
            "fresh_imagery_price": 25,
            "standard_imagery_price": 20,
            "training_imagery_price": 5
        },
        "limits": {
            "annual_subscription_fee_limit": 15000,
            "fresh_imagery_fee_limit": 20000,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1,
            "tasking_imagery_fee_limit": 5000
        }
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/admin/account/56000981894273578..",
        "users": "https://ard.maxar.com/api/v1/admin/account/56000981894273578../user",
        "applications": "https://ard.maxar.com/api/v1/admin/account/56000981894273578../application",
        "credentials": "https://ard.maxar.com/api/v1/admin/account/56000981894273578../credentials"
    },
    "response_timestamp": "2022-06-03T15:14:08Z"
}

List orders for the account¶

Account administrators can list the orders placed under their account. Limit the results by adding query parameters to the request. Orders are sorted from newest to oldest.

See Accounts API Reference for more information.

User Management¶

Account admins can add, update, list, and disable users within the account they belong to. The account ID is required for all user management activities.

When a user is added to the account, they will receive a welcome email with temporary credentials and a link to change their password. The password must be changed within seven days. Once the invitation expires, you will need to make a "resend verification" request to send them a new active link. This request is detailed below.

Path parameters¶

Path parameters are surrounded with curly brackets { } in the examples below.

param	description
account_id	The ID of the account the user will be added to. Account administrators can only add users to the account they belong to. This is used for all user requests; such as create, update, deactivate, or list users.
user_id	The id associated with a user record. This is used in the URL path when updating, deactivating, or reactivating a user.

Body parameters¶

param	required	default	description
active	no	true	true/false. To deactivate a user, set this field value to "false."
admin	no	false	true/false. Include this field with a value of "true" if the user will be an account administrator.
country_code	yes	no default	ISO-3166-1-alpha-3 three-character country code where the user resides. See country code list for 3-digit codes. Must be submitted in all caps.
email	yes	no default	user's email address in valid format, i.e. customer@myemail.com. Email cannot be changed once it's submitted.
name	yes	no default	user's full name

Create a user¶

Create a single user or multiple users in a request.

Request method: POST

First, Add your account_id as a parameter to the following path (with the admin root URL):

/api/v1/admin/account/{account_id}/users

Then, build the request body, using the required fields and any optional fields listed in the User Parameters table above.

Example: Create a single user¶

{
    "name": "Ally Harrison",
    "email": "allyson@myemail.com",
    "country_code": "DNK",
    "sqkm_limit": 500
}

Example: Create an account administrator¶

{
    "name": "Brian Taylor",
    "email": "btaylor@myemail.com",
    "country_code": "USA",
    "admin": true,
    "sqkm_limit": 500
}

Example: Create multiple users in one request¶

{
    "users": [
        {
          "name": "Ally Harrison",
          "email": "allyson@myemail.com",
            "country_code": "DNK",

        },
        {
          "name": "Brian Taylor",
          "email": "btaylor@myemail.com",
            "country_code": "USA",
          "admin": true,

        }
    ],
    "sqkm_limit": 500
}

Resend verification¶

Resend a verification email to a user.

Request method: POST

If an invited user does not use their temporary credentials to change their password within seven days, the link will expire. You can resend a verification email with a new active link.

To send a new verification email, add the account ID and the recipient's user ID parameters to the request path and send the request.

/api/v1/admin/account/{account_id}/user/{user_id}/resend_verification

Update a user record¶

Update a user's information.

Request method: PATCH

To make a change to a user record, only include the parameter that will be updated in the request body.

When updating a user record, it's important to know:

Email address cannot be updated.
Updating an inactive user record reactivates the user.
only include the parameters that will be updated.

To update a user record, include the account ID and the recipient's user ID as path parameters.

/api/v1/admin/account/{account_id}/user/{user_id}

Then, build a request body with only the fields that need to be updated. Do not add any fields that don't require an update.

In this example request body, we'll change a user record's country code and increase the sqkm limit.

{
    "country_code": "ATA",
    "sqkm_limit": 800
}

Deactivate a user¶

Remove a user's ability to access or use the ARD system.

Deactivating a user removes their access to the Maxar ARD system to select and order imagery. It does not delete data from their user record and does not impact usage data. Deactivated users can be re-activated.

Request method: DELETE

To deactivate a user, add the account ID and user ID as path parameters.

/api/v1/admin/account/{account_id}/user/{user_id}

Reactivate a user¶

Submitting an "update" request automatically reactivates a user. For example, if you update the country code for a deactivated user, they will automatically be reactivated.

Reactivating a user gives them immediate access to the Maxar ARD system to select and order imagery. To activate a user without updating any other data, submit a request body with active: true.

Request method: PATCH

Add account ID and user ID as path parameters.

api/v1/admin/account/{account_id}/user/{user_id}

Then, create a request body with "active": true

  {
      "active": true
  }

Other ways to reactivate a user record:

Make any update to the user's record (except email address) with a PATCH request.
Send a PATCH request with an empty request body.

Example:

   {

   }

Delete a user¶

Deleting a user permanently removes their data from the user table and removes their usage data. Once a user record is deleted, it cannot be recovered. Deleting a user record is not supported in the API.

To request the deletion of a user record, email ARD Support with an explanation of why the user needs to be deleted instead of deactivated.

List all users in the accounts¶

List all users in an account, or list only active users. Listing active users only is the default for this request. This request returns information about each user in the list.

Note: Listing users is the easiest way to find the user ID for a specific person. You need the user ID for most of the requests shown on this page.

Example: List active users in the account¶

Request method: GET

/api/v1/admin/account/{account_id}/user

Example: List all users in the account¶

To see a list of both active and inactive users in the account, append ?active_only=false to the request URL:

/api/v1/admin/account/{account_id}/user?active_only=false

Get the record for a specific user¶

View data for a specific user

Request method: GET

Send the following URL with account ID and user ID as path parameters

/api/v1/admin/account/:account_id/user/{user_id}

Frequently asked questions¶

Q. How do I find my account ID?¶

In the ARD Postman collection, open the "Authentication" directory and choose "Get Self." This will return your user information, including the ID for the account you belong to.

Request method: GET

api/v1/auth/self

Response:

{
    "user": {
        "account_id": "5589150080369207736",
        "name": "ARD User",
        "active": true,
        "sqkm_limit": null,
        "admin": true,
        "created": "2021-03-12T21:14:17Z",
        "modified": "2021-03-12T21:14:18Z",
        "user_id": "967f13a5-1d80-4o74-9334-fcae93fd203f",
        "country_code": "USA",
        "job_title": null,
        "email": "demo-user@gmail.com"
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/admin/account/5589...",
        "account": "https://ard.maxar.com/api/v1/admin/account/..."
    },
    "response_timestamp": "2021-06-07T15:15:31Z"

}

Q. How do I find a user ID?¶

To find the user ID for someone in your account, make a "list all users" request. See the example earlier in this document. This request lists all users with their user data.

Q. How do I update a user's email address?¶

If an email address for a user needs to be updated, deactivate the user record and create a new one with the new email address. The user will receive the welcome email again with new temporary credentials, and they will need to change their password.