Skip to content

User Resource

Last updated: January 23, 2023

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 requests

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": 5000,
        "fresh_imagery_fee_limit": 0,
        "standard_imagery_fee_limit": -1,
        "training_imagery_fee_limit": -1,
        "tasking_imagery_fee_limit": 0
    }
}

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": "sheamullins@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"
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 $10000, and the administrator for this account may allocate 50000 to an individual user. "annual_subscription_fee_limit": 5000
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. training_imagery_fee_limit": -1
tasking_imagery_fee_limit The limit set for imagery collected by a tasking request. This fee limit is separate from the annual subscription fee limit. "tasking_imagery_fee_limit": 5000.00

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. This does not apply to the tasking imagery fee limit.

Reponse

Status: 201 Created

{
    "user": {
        "account_id": "557471230760500000",
        "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": 5000.0,
            "fresh_imagery_fee_limit": 3000.0,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1,
                        "tasking_imagery_fee_limit": 8000.0
        }
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/admin/account/557471230760500000/user/095af94cf-47e1-a342-d654572b9390",
        "account": "https://ard.maxar.com/api/v1/admin/account/557471230760500000"
    },
    "response_timestamp": "2022-012-15T18:06:54Z"
}

Response fields

field description example
account_id The ID for the account where the user was created. "account_id": "557471230760500000"
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"
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"
fresh_imagery_fee_limit The fresh imagery fee limit set for the user. If no limit is set, the account's limit applies. "fresh_imagery_fee_limit": 3000.0
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": -1
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": -1
tasking_imagery_fee_limit The limit set for imagery collected by a tasking request. This fee limit is separate from the annual subscription fee limit. "tasking_imagery_fee_limit": 5000.00
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": "557471230760500000",
            "name": "User 1",
            "active": true,
            "created": "2021-03-12T21:14:16Z",
            "modified": "2021-07-21T12:44:46Z",
            "user_id": "85914d9c-d5d8-4903-a89d999",
            "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
            }
        },

        {
            "account_id": "557471230760500000",
            "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
            }
        }
    ],
    "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. 557471230760500000
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