Skip to content

User Resource

Description: Create, update, deactivate user records.

Last updated: August 29, 2022


User

/admin/account/user
Create, update, and deactivate users. List all users or get a specific user's data.

See also: Account Administration User Guide.

User Resources

http method path description role required
POST /admin/account/{account_id}/user Create a user in an account. admin
POST /admin/account/{account_id}/user/{user_id}/resend_verification Resend a verification email to user. admin
PATCH admin/account/{account_id}/user/{user_id} Update one or more fields on a user record, or reactivate a user. admin
DELETE /admin/account/{account_id}/user/{user_id} Deactivate a user record. This request sets a user's record to "active":false, which prevents the user from getting an ARD access token or accessing ARD resources. It does not remove the user's data. admin
GET admin/account/{account_id}/user List users in an account. admin
GET /admin/account/{account_id}/user/{user_id} Get the details of a user record. Admins can get details for any user in the account they administer. Users can see their own use record details. admin, user

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.

Create a User

Create a single user record in an account.

See Users Resource to create a batch of users in a single request.

POST /admin/account/{account_id}/user
Role: Admin

Path parameters

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

Request body

Example

{
    "name": "Shea Mullins",
    "email": "shea@myemail.com",
    "country_code": "USA",
    "admin": false,
    "job_title": "data scientist",
    "limits": {
        "annual_subscription_fee_limit": 500,
        "fresh_imagery_fee_limit": -1,
        "standard_imagery_fee_limit": -1,
        "training_imagery_fee_limit": -1,
        "sqkm_limit": -1
    }
}

Request body parameters

param required description example
admin optional To create another admin in your account, add "admin":true. The default is false. "admin": true
country_code required ISO-3166-1-alpha-3 three-character country code where the user resides. See county codes. country_code": "USA"
email required A valid email address for the user. This value cannot be changed later. "email": "username@myemail.com"
limits optional Fee limits set for the users. If no fee limits are set, the account's fee limits apply. See the table below for field descriptions.
job_title optional The user's job title. This value can be any string. "job_title": "data scientist"
name required The user's full name "name": "Shea Mullins"
sqkm_limit optional Set a square kilometer usage limit for this user. If no limit is set, the account limit applies. "sqkm_limit": 500
Limits

Accounts and users can both have category fee limits set. If no limits are set for the user, the account's limits apply. The user's limits cannot be greater than the account's limits. All fields in this table are optional.

name description example
annual_subscription_fee_limit This is an annual fee limit set for the individual user. The value is a dollar amount. For example, an account may have an annual_subscription_fee_limit of 500000 ($500,000), and the administrator for this account may allocate 100000 ($100,000) to an individual user. "annual_subscription_fee_limit": 500
fresh_imagery_fee_limit The limit set for imagery in the "fresh" imagery age category. Once the limit has been met for this category, no more "fresh" imagery can be ordered. If the fee limit is set to zero "0", imagery from this category cannot be ordered. fresh_imagery_fee_limit": 500
standard_imagery_fee_limit The limit set for imagery in the "standard" imagery age category. Once the limit has been met for this category, no more "standard" imagery can be ordered. If the fee limit is set to zero "0", imagery from this category cannot be ordered. standard_imagery_fee_limit": -1
training_imagery_fee_limit The limit set for imagery in the "training" imagery age category. Once the limit has been met for this category, no more "training" imagery can be ordered. If the fee limit is set to zero "0", imagery from this category cannot be ordered. fresh_imagery_fee_limit": -1

See also: Account Usage Guide

The default value for the limit fields is null or -1.

Note: The value set for any '[category]_fee_limit' cannot be greater than the value set for the annual subscription fee limit. If any single category limit exceeds the annual subscription fee limit, the account creation or update request will return an error.

Reponse

Status: 201 Created

{
    "user": {
        "account_id": "555523490000000",
        "name": "Shea Mullins",
        "active": true,
        "admin": false,
        "created": "2021-07-15T18:06:53Z",
        "modified": "2021-07-15T18:06:54Z",
        "user_id": "25af94cf-b031-47e1-a342-d65>>>",
        "country_code": "USA",
        "job_title": "data scientist",
        "email": "shea@myemail.com",
        "limits": {
            "annual_subscription_fee_limit": 900.0,
            "fresh_imagery_fee_limit": 500,
            "standard_imagery_fee_limit": null,
            "training_imagery_fee_limit": null,
            "sqkm_limit": -1
        }
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/admin/account/555523490000000/user/095af94cf-47e1-a342-d654572b9390",
        "account": "https://ard.maxar.com/api/v1/admin/account/5699953481120981433"
    },
    "response_timestamp": "2021-07-15T18:06:54Z"
}

Response fields

field description example
account_id The ID for the account where the user was created. "account_id": "555523490000000"
name The user's full name. "name": "Shea Mullins"
active The user's active/inactive status. A value of "true" means the user is active and has access to ARD resources. A value of "false" means the user record has been deactivated. "active": true
admin If the admin value is "true", the user has been assigned the admin role. "admin": true
annual_subscription_fee_limit The total imagery fee limit set for the user. If no limit is submitted, the account limits apply. "annual_subscription_fee_limit": 900.0
country_code The ISO-3166-1-alpha-3 three-character country code where the user resides. country_code": "USA"
created The date the user record was created. "created": "2021-07-15T18:06:53Z"
fresh_imagery_fee_limit The fresh imagery fee limit set for the user. If no limit is set, the account's limit applies. "standard_imagery_fee_limit": null
job title The user's job title. job_title": "data scientist"
modified The date the user record was last modified with an update request. "modified": "2021-07-18T18:06:53Z"
response_timestamp Indicates the time the response to the request was returned. "response_timestamp": "2021-07-15T18:06:54Z
sqkm_limit The sqkm_limit set for the user. If no limit is set, the account's limit applies. "sqkm_limit": -1
standard_imagery_fee_limit The standard imagery fee limit set for the user. If no limit is set, the account's limit applies. "standard_imagery_fee_limit": null
training_imagery_fee_limit The training imagery fee limit set for the user. If no limit is set, the account's limit applies. "training_imagery_fee_limit": null
user_id The ID assigned to the user. "user_id": "25af94cf-b031-47e1-a342-d65>>>"
link description
self URL to a "get self" request.
account URL to account details.

Resend verification email to user

Resend a verification email if a user did not use their temporary credentials to change their password before the link expired.

POST /admin/account/{account_id}/user/{user_id}/resend_verification

Role: Admin

Response Code

Status: 200 OK

Update a user record

Update one or more fields on a user record, or reactivate a user.

PATCH /admin/account/{account_id}/user/{user_id}

Role: Admin

Request body

Include only the fields that should be updated in the request body.

Example: Update name and country code.

{
    "name": "Shea Barnes",
    "country_code": "CAN",

}

Note: The email field cannot be updated. If a user's email address needs to be changed, deactivate the record and create a new one for the user.

Response code

Status: 200 OK

See the response body for the Create a User request above.

Deactivate a user

Deactivate a user record. This request sets a user's record to "active":false, which prevents the user from getting an ARD access token or accessing ARD resources. It does not remove the user's data.

DELETE /admin/account/{account_id}/user/{user_id}

Role: Admin

Response code

Status: 204 No Content

List users in the account

List users in an account.

GET /admin/account/{account_id}/user

Role: Admin

Query parameters

Response

Status: 200 OK

{
    "users": [{
            "account_id": "5568860438844188876",
            "name": "User 1",
            "active": true,
            "created": "2021-03-12T21:14:16Z",
            "modified": "2021-07-21T12:44:46Z",
            "user_id": "85914d9c-d5d8-4903-a89d...",
            "country_code": "USA",
            "job_title": "technical lead",
            "email": "user1@myemail.com",
            "limits": {
                "annual_subscription_fee_limit": 2050,
                "fresh_imagery_fee_limit": -1,
                "standard_imagery_fee_limit": null,
                "training_imagery_fee_limit": -1,
                "sqkm_limit": null
            }
        },

        {
            "account_id": "5568860438844188876",
            "name": "User 2",
            "active": true,
            "admin": false,
            "created": "2021-04-23T13:17:57Z",
            "modified": "2021-04-23T13:17:58Z",
            "user_id": "85914d9c-d5d8-4903-a89d0000",
            "country_code": "USA",
            "job_title": "manager",
            "email": "user2@myemail.com",
            "limits": {
                "annual_subscription_fee_limit": 1500,
                "fresh_imagery_fee_limit": -1,
                "standard_imagery_fee_limit": -1,
                "training_imagery_fee_limit": -1,
                "sqkm_limit": null
            }
        }
    ],
    "response_timestamp": "2021-07-21T17:16:20Z"
}

Get user details

GET /admin/account/{account_id}/user/{user_id}

Get the details of a user record by ID.

Role: Admin

Path parameters

param description example
account_id The ID for the account where the credentials will be registered. 9999636127253830000
user_id The ID for the user you request acccount details for. 85914d9c-d5d8-4903-a89d0000

Response

Status: 200 OK

See response for Create a user request.

More Documentation

Account Administration Guide

Create a batch of users

Back to top