How to use the Azure Stack Hub API

Overview

The Azure Stack Hub API enables you to interact programmatically with your UKCloud for Microsoft Azure environment. For example, you can use API calls to manage your UKCloud for Microsoft Azure tenancy.

This article shows you how to get started with the Azure Stack Hub API.

When interacting with Azure Stack Hub resources via the API, you must specify an API version. You can find a full list of supported API versions here.

Prerequisites

To complete the steps in this article, you must have appropriate access to a subscription on Azure Stack Hub and permissions on the resources you are trying to access.

Authenticating to the API

Azure Stack Hub API authentication uses access tokens to validate requests.

To obtain an access token:

  1. Send a POST request to the Azure REST authentication/login endpoint:

    https://login.microsoftonline.com/<tenant_id>/oauth2/token

    where tenant_id is one of the following:

    • Your tenant domain, for example: ukcloud.onmicrosoft.com, ukcloud.com, example.mydomain.com

    • Your tenant ID, for example: 8eaef023-2b34-4da1-9baa-8bc8c9d6a490

    • The default value for tenant independent keys: common

  2. Pass the following parameters in the request body:

    • grant_type - The type of authentication scheme to use: password

    • client_id - Hard-coded to a default value of 1950a258-227b-4e31-a9cf-717495945fc2

      Other options for specific scenarios are:

      • PowerShell - 1950a258-227b-4e31-a9cf-717495945fc2

      • LegacyPowerShell - 0a7bdc5c-7b57-40be-9939-d4c5fc7cd417*

      • WindowsAzureActiveDirectory - 00000002-0000-0000-c000-000000000000

      • VisualStudio - 872cd9fa-d31f-45e0-9eab-6e460a02d1f1

      • AzureCLI - 04b07795-8ddb-461a-bbee-02f9e1bf7b46

    • resource - The endpoint of the resource that the token will be used to access, for example: https://management.as2ukcloud.onmicrosoft.com/90ada28c-5aed-4248-90c7-0538504217f1

      Note

      You can obtain the resource endpoint by querying the Azure Stack Hub management metadata endpoint. The resource endpoint is returned in the audiences section of the response.

      It is constructed like this: https://management.<region>.<AzureStackHubFQDN>/metadata/endpoints?api-version=2017-12-01

      For example, to find the endpoint for the users resource, send a request to https://management.frn00006.azure.ukcloud.com/metadata/endpoints?api-version=2017-12-01.

      Tip

      For Azure Stack Hub administrators (operators) add admin to the request.

      For example, to find the endpoint for the operators resource, send a request to https://adminmanagement.frn00006.azure.ukcloud.com/metadata/endpoints?api-version=2017-12-01.

    • username - The Azure Stack Hub AAD account, for example: user@contoso.onmicrosoft.com

    • password - The password for the Azure Stack Hub AAD account

    Note

    Ensure you format the request body using Content-Type x-www-form-urlencoded.

Declare variables

Enter details below to provide values for the variables in the scripts in this article:

Variable name Variable description Input
$Tenant The tenant ID or domain to authenticate to
$AzureStackUsername The username of a user for Azure Stack Hub
$AzureStackUserPassword The password of a user for Azure Stack Hub
$ClientID The application ID to authenticate against the Azure Stack Hub API 
# Send POST request to Azure REST authentication/login endpoint to retrieve access token. 
curl -X "POST" "https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=1950a258-227b-4e31-a9cf-717495945fc2" \
--data-urlencode "grant_type=password" \
--data-urlencode "username=user@contoso.onmicrosoft.com \
--data-urlencode "password=Password123!" \
--data-urlencode "resource=https://management.as2ukcloud.onmicrosoft.com/90ada28c-5aed-4248-90c7-0538504217f1"

  1. If the authentication is successful, the endpoint returns an access token, for example:

    {
  "token_type": "Bearer",
  "scope": "user_impersonation",
  "expires_in": "3599",
  "ext_expires_in": "0",
  "expires_on": "1512574780",
  "not_before": "1512570880",
  "resource": "https://management.as2ukcloud.onmicrosoft.com/90ada28c-5aed-4248-90c7-0538504217f1",
  "access_token": "eyJ0eXAiOi...truncated for readability...",
  "refresh_token": "AQABAAAAAA...truncated for readability..."
}

  2. You must include this token in the Authorization header of each subsequent API request, for example:

    curl -H "Authorization: Bearer eyJ0eXAiOi...truncated for readability..." 'https://management.frn00006.azure.ukcloud.com/subscriptions?api-version=2017-12-01'

Calling Azure Stack Hub API endpoints

A REST request URI consists of:

<URI-scheme>://<URI-host>/<resource-path>?<query-string>

where:

  • URI-scheme is the protocol used to transmit the request, for example http or https

  • URI-host is the domain name or IP address of the server where the REST service endpoint is hosted, for example: management.frn00006.azure.ukcloud.com

  • resource path is the resource or resource collection used by the service in determining the selection of those resources (the path may include multiple segments), for example: /subscriptions is the resource path to obtain information about Azure Stack Hub subscriptions

  • query-string provides additional parameters, such as the API version or resource selection criteria

    Note

    For Bash, you can add the query-string to the end of the request URI following a question mark. For example, to specify use of a specific API version: https://management.frn00006.azure.ukcloud.com/subscriptions?api-version=2017-12-01.
    For PowerShell, you can provide a query-string in the -Body parameter hash table. For example: -Body @{"api-version" = "2017-12-01"}

The syntax of an Azure Stack Hub request URI is:

https://management.frn00006.azure.ukcloud.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/<provider>/<resource-path>?<filter-expression>&api-version=<api-version>

where:

  • subscription-id is your tenant subscription ID

  • resource-group is the resource group you want to query

  • provider is the provider you want to query

  • resource-path is the resource you want to query

  • filter-expression is an optional list of arguments to filter the results of the query

  • api-version is the version of the Azure Stack Hub API being called, for example: api-version=2017-12-01

For example, the following API call returns the VM: Windows-VM located in the resource group: MY-WINDOWS-VM-RG in the specified Azure Stack Hub subscription:

https://management.frn00006.azure.ukcloud.com/subscriptions/800c4168-3eb1-405b-a4ca-919fe7ee42e9/resourceGroups/MY-WINDOWS-VM-RG/providers/Microsoft.Compute/virtualMachines/Windows-VM?api-version=2017-12-01

Tip

To query a top level API resource, such as virtual machines, use the following example:

https://management.frn00006.azure.ukcloud.com/subscriptions/800c4168-3eb1-405b-a4ca-919fe7ee42e9/providers/Microsoft.Compute/virtualMachines?api-version=2017-12-01

Next steps

For general information about the Azure API, see the Azure REST API Reference at:

Azure API documentation page

In particular, you may find the following documents useful:

This is guidance for Azure Stack Hub users. Currently, there is no official API reference guide for Azure Stack Hub users; however, there is an admin API guide that you can find here. We'll update this article when an API guide becomes available.

For more information about UKCloud for Microsoft Azure, see:

Feedback

If you find a problem with this article, click Improve this Doc to make the change yourself or raise an issue in GitHub. If you have an idea for how we could improve any of our services, send an email to feedback@ukcloud.com.