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]_

.. table:: 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:

.. code:: bash

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

Example response showing subscription details:

.. code:: http

   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:

.. code:: bash

   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:

.. code:: http

   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:

.. code:: bash

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

Example response showing a list of storage accounts:

.. code:: http

   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:

.. code:: bash

   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:

.. code:: http

   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:

.. code:: text

   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:

.. code:: bash

   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:

.. code:: http

   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:

.. code:: bash

   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:

.. code:: http

   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.