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:
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
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 tohttps://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 tohttps://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//oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=" \
--data-urlencode "grant_type=password" \
--data-urlencode "username= \
--data-urlencode "password=" \
--data-urlencode "resource=https://management.as2ukcloud.onmicrosoft.com/90ada28c-5aed-4248-90c7-0538504217f1"
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..." }
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
orhttps
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 subscriptionsquery-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:
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.