Managing Your Azure AirMettle Select Resources with the Admin API

The Admin API is a RESTful API that allows you to manage your Azure AirMettle Select resources programmatically. You can use it to add and manage storage accounts, view and update your subscription details, and more.

The service responds with standard HTTP status codes to indicate if your request was successful or not, including 200-series codes for success, 400-series codes for client errors, and 500-series codes for server errors.

HTTPS is enforced for data integrity and confidentiality.

All request and response bodies are in JSON format unless otherwise specified.

Authentication

Every request must include your Subscription ID and API key in the headers x-subscription-id and x-api-key for authentication. [1]

Examples of a Subscription ID and API key

Name	Example
Subscription ID	21054712-baff-47cc-b924-8ab1f9e66f17
API Key	9f8e7d6c5b4a3c2d1e0f9a8b7c6d5e4f

In the request examples in the following sections, replace SUBSCRIPTION_ID and API_KEY with your Subscription ID and API key to authenticate your requests.

Requests without valid credentials will be rejected with a 401 Unauthorized response. Requests with insufficient permissions will be rejected with a 403 Forbidden response.

Sending Requests

Subscription Management

The Admin API provides an endpoint to manage your subscription, including viewing administrator details and subscription information.

The /api/v1/subscription endpoint accepts GET and PATCH requests to retrieve or update your subscription details, respectively.

GET /api/v1/subscription

Retrieve details about your subscription, including plan information and administrator contact details.

Example command to retrieve subscription details:

curl /api/v1/subscription \
  -H 'x-subscription-id: SUBSCRIPTION_ID' \
  -H 'x-api-key: API_KEY'

Example response showing subscription details:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "21054712-baff-47cc-b924-8ab1f9e66f17",
  "admin_email": "admin_email@example.com",
  "created_at": "2023-10-01T12:00:00Z"
}

PATCH /api/v1/subscription

Update your subscription details, such as changing contact information.

Only include the fields you wish to update in the request.

Example command to update subscription details:

curl -X PATCH /api/v1/subscription \
     -H 'x-subscription-id: SUBSCRIPTION_ID' \
     -H 'x-api-key: API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "admin_email": "new_email@example.com"
         }'

Example response showing updated subscription details:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "21054712-baff-47cc-b924-8ab1f9e66f17",
  "admin_email": "new_email@example.com",
  "created_at": "2023-10-01T12:00:00Z"
}

Storage Account Management

The Admin API provides an endpoint to manage the storage accounts you want to use with Azure AirMettle Select, including adding new accounts, listing existing ones, updating account details, and deleting accounts.

The /api/v1/buckets endpoint accepts GET, POST, PATCH, and DELETE requests to retrieve, create, update, or delete storage accounts, respectively.

“Storage Account ID” or “ID” in this section refer to the unique identifier assigned to each storage account when it is added to your subscription using the POST /api/v1/buckets endpoint.

GET /api/v1/buckets

Retrieve a list of all storage accounts associated with your subscription.

Example command to list all storage accounts associated with your subscription:

curl /api/v1/buckets \
     -H 'x-subscription-id: SUBSCRIPTION_ID' \
     -H 'x-api-key: API_KEY'

Example response showing a list of storage accounts:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "subscription_id": "21054712-baff-47cc-b924-8ab1f9e66f17",
      "id": "10ac45f6-4aff-44a6-bd4d-43b741be70a8",
      "storage_account": "airmettlestore123",
      "created_at": "2023-10-01T12:00:00Z"
    },
    {
      "subscription_id": "21054712-baff-47cc-b924-8ab1f9e66f17",
      "id": "20bc56g7-5bff-55b7-ce5e-54c852cf81b9",
      "storage_account": "anotherstore456",
      "created_at": "2023-10-02T15:30:00Z"
    }
  ]
}

GET /api/v1/buckets/{id}

Retrieve details about a specific storage account by its ID.

Example command to retrieve details of a specific storage account by its ID:

curl /api/v1/buckets/10ac45f6-4aff-44a6-bd4d-43b741be70a8 \
     -H 'x-subscription-id: SUBSCRIPTION_ID' \
     -H 'x-api-key: API_KEY'

Example response showing details of the specified storage account:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "subscription_id": "21054712-baff-47cc-b924-8ab1f9e66f17",
  "id": "10ac45f6-4aff-44a6-bd4d-43b741be70a8",
  "storage_account": "airmettlestore123",
  "created_at": "2023-10-01T12:00:00Z"
}

POST /api/v1/buckets

Add a new storage account to your subscription.

All fields listed below are required.

Azure AirMettle Select accesses your storage account using the account key you provide. You may retrieve this key from the Azure Portal.

Example of an account key used to authenticate access to an Azure Storage account:

QWErty12345ZXCVbnm67890AbCdEfGhIjKlMnOpQrStUvWxYz0123456789==

Rotating the account key may prevent Azure AirMettle Select from accessing your storage account. If you rotate the key, let us know using the PATCH /api/v1/buckets/{id} endpoint to ensure uninterrupted service.

Example command to add a new storage account to your subscription:

curl -X POST /api/v1/buckets \
     -H 'x-subscription-id: SUBSCRIPTION_ID' \
     -H 'x-api-key: API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "storage_account": "airmettlestore123",
           "account_key": "QWErty12345ZXCVbnm67890"
         }'

Example response showing details of the newly added storage account:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "subscription_id": "21054712-baff-47cc-b924-8ab1f9e66f17",
  "id": "10ac45f6-4aff-44a6-bd4d-43b741be70a8",
  "storage_account": "airmettlestore123",
  "created_at": "2023-10-01T12:00:00Z"
}

PATCH /api/v1/buckets/{id}

Update details of an existing storage account, such as changing the account key.

Example command to update details of an existing storage account:

curl -X PATCH /api/v1/buckets/10ac45f6-4aff-44a6-bd4d-43b741be70a8 \
     -H 'x-subscription-id: SUBSCRIPTION_ID' \
     -H 'x-api-key: API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "account_key": "ACCOUNT_KEY"
         }'

Example response showing updated details of the storage account:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "subscription_id": "21054712-baff-47cc-b924-8ab1f9e66f17",
  "id": "10ac45f6-4aff-44a6-bd4d-43b741be70a8",
  "storage_account": "airmettlestore123",
  "created_at": "2023-10-01T12:00:00Z"
}

Note that sensitive fields such as account_key are not included in the response.

Include only the fields you wish to update.

DELETE /api/v1/buckets/{id}

Delete a storage account from your subscription.

This prevents any further queries to blobs in that account.

Note that this action does not delete any data in your Azure Storage account, including any metadata files generated by Azure AirMettle Select, or the account itself.

[1]

When using the Query CLI, these credentials are included in the request payload or headers, depending on the client.