Programmatically invite Users to Azure API Management

Azure API Management (APIM) is a service that allows you to create modern API gateways for existing back-end services. In addition, it also comes with a Developer portal that serves as the main web presence for developers working with your APIs where they can invoke your endpoints and read your API documentation.

This article shows how to programmatically invite developers to your Azure API Management instance using PowerShell and the APIM REST API.

Note: If you want to create new users with a predefined password, you can use the New-AzApiManagementUser cmdlet instead of dealing with REST calls. For more information on managing user accounts, see the official “How to manage user accounts in Azure API Management” documentation.

Prerequisites

• Azure Subscription
• PowerShell
• Azure API Management service instance
• Azure CLI

Sign in with Azure CLI

We will use the Azure CLI to perform a REST request to the APIM API.  Before we can do that, we have to log in to Azure first. There are several different authentication types for the Azure CLI available. For demo purpose, we will sign in interactively through the browser using the az login command:

az login	

Note: If you have multiple subscriptions, ensure you have selected the desired one as the default subscription. See change your default subscription.
In addition, if you want to include the authentication step as part of the following script, the recommended approach is to use a service principal.

Define the users

We will use a JSON file to store the users we want to invite to our API Management instance. This is how my users.json file looks like:

[
    {
        "FirstName": "Max",
        "LastName": "Mustermann",
        "Email": "max.mustermann@about-azure.com"
    },
    {
        "FirstName": "John",
        "LastName": "Doe",
        "Email": "john.doe@about-azure.com"
    }
]

Invite the users

The endpoint we are looking for to invite users to our APIM instance is the User – Create or Update endpoint :

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/users/{userId}?api-version=2019-12-01

Within the request body, we have to specify three properties:

• properties.email
• properties.firstName
• properties.lastName

Before we can invoke the endpoint, we have to load our users.json and convert it to a PSCustomObject using the ConvertFrom-Json cmdlet:

$users = Get-Content 'users.json' | ConvertFrom-Json

We also have to define some variables for the resource group, the subscription id, and the Azure API Management instance name:

$resourceGroup = 'my-apim-rg'
$apimName = 'my-apim-name'
$subscriptionId = 'my-subscription-id'

Now we can invoke the endpoint using the az rest command. In line 2, we create the user id using the email property with non-word characters before we populate the whole request URI in line 3.

Due to a known PowerShell issue which causes double quotes to get lost when calling a native .exe file (like az) we won’t pass the request body directly to the az rest command. To bypass the shell’s interpretation mechanisms, we will save the body in a temporary file and pass it using the @<file> convention in line 18:

$users | ForEach-Object {
    $userId = $_.Email -replace '\W', '-'
    $uri = "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ApiManagement/service/$apimName/users/$($userId)?api-version=2019-12-01"

    try {
        $tmpFile = New-TemporaryFile

        @{
            properties = @{
                confirmation = "invite"
                firstName    = $_.FirstName
                lastName     = $_.LastName
                email        = $_.Email
                appType      = "developerPortal"
            }
        } | ConvertTo-Json -Compress | Out-File $tmpFile

        az rest --method put --uri $uri --body @$tmpFile    
    }
    finally {
        Remove-Item $tmpFile
    }
}

After executing the script, we will find our user John Doe and Max Mustermann within the Azure API Management service:

The whole script and a sample users.json are available on GitHub.