Authenticate

Authenticate to the API

AZExecute uses Microsoft Entra OAuth 2.0 bearer tokens. Choose a delegated flow when a person is acting interactively, or client credentials when an application or automation identity acts without a signed-in user.

• Delegated clients request https://api.azexecute.com/Standard.Access.

• Service principals request https://api.azexecute.com/.default and must have an assigned API app role.

• Send the resulting token as Authorization: Bearer <access-token>.

• Acquire a new token after changing app-role assignments; existing tokens retain their original claims until renewed.

After authentication, use API Swagger to inspect the supported operations, required roles, request bodies, and response schemas for the deployed API version.

Azure CLI - Delegated User Token

Use this flow to obtain a delegated user token with the API scope configured for AZExecute.

A user's effective tenant role is resolved when the token is processed. After changing an Entra app-role assignment, acquire a fresh token; an existing access token can continue to contain the previous role until it is renewed.

# Step 1: Log in and request the delegated API scope
$scope = 'https://api.azexecute.com/Standard.Access'
az login --scope $scope
$tokenResponse = az account get-access-token --scope $scope | ConvertFrom-Json

# Extract the access token
$accessToken = $tokenResponse.accessToken

# Step 2: Use the access token to call your API
$headers = @{
    Authorization = "Bearer $accessToken"
    Accept        = 'application/json'
}

# Make the API call
$response = Invoke-RestMethod -Method Get -Uri 'https://api.azexecute.com/api/v1/Application' -Headers $headers

# Output the response
$response

Client Credentials Flow with PowerShell

Use this flow when authenticating as a service principal that has been assigned an API access role.

1. Create or select a Microsoft Entra app registration for the client.

2. Assign its enterprise application the minimum required AZExecute API app role: User, Operator, or TenantAdmin.

3. Configure a client secret, certificate, federated credential, or managed identity credential appropriate for your environment.

4. Request a token from the tenant-specific token endpoint using the .default scope.

The sample uses a client secret for readability. Prefer a certificate, workload identity federation, or managed identity when your hosting platform supports it. Never place credentials in source control.

# Define the tenant ID, client ID, and client secret
$tenantId = ''
$clientId = ''
$clientSecret = ''
$scope = 'https://api.azexecute.com/.default'
$tokenUrl = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

# Prepare the body parameters
$body = @{
    grant_type    = 'client_credentials'
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scope
}

# Request the token
$response = Invoke-RestMethod -Uri $tokenUrl -Method Post -ContentType 'application/x-www-form-urlencoded' -Body $body

# Extract the access token from the response
$accessToken = $response.access_token

$headers = @{
    Authorization = "Bearer $accessToken"
    Accept        = 'application/json'
}

# Make the API call
$response = Invoke-RestMethod -Method Get -Uri 'https://api.azexecute.com/api/v1/Application' -Headers $headers

Common Authentication Errors

• 401 Unauthorized: the token is missing, expired, malformed, or issued for the wrong audience.

• 403 Forbidden: authentication succeeded, but the identity lacks the required API role or access to the requested resource.

• Role change not visible: obtain a fresh token and verify its roles claim.

• Client credentials rejected: verify the tenant ID, client ID, credential, .default scope, and enterprise-application role assignment.

Authorization Code Flow for Web Apps

This flow is used for web applications where a user needs to log in interactively.

# Authorization Code Flow for Web Apps
# Step 1: Redirect user to login with the delegated API scope
https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    ?client_id={clientId}
    &response_type=code
    &redirect_uri={redirectUri}
    &response_mode=query
    &scope=openid%20profile%20offline_access%20https://api.azexecute.com/Standard.Access
    &state=12345

# Step 2: Use the authorization code to get an access token
$tokenUrl = 'https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token'
$body = @{
    grant_type    = 'authorization_code'
    client_id     = '{clientId}'
    client_secret = '{clientSecret}'
    code          = '{authCode}'
    redirect_uri  = '{redirectUri}'
    scope         = 'https://api.azexecute.com/Standard.Access'
}
$response = Invoke-RestMethod -Uri $tokenUrl -Method Post -ContentType 'application/x-www-form-urlencoded' -Body $body
$accessToken = $response.access_token

Device Code Flow

This flow is useful when logging in on a device without a browser.

# Device Code Flow
# Step 1: Request device code
$deviceCodeResponse = Invoke-RestMethod -Uri 'https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/devicecode' -Method Post -ContentType 'application/x-www-form-urlencoded' -Body @{
    client_id = '{clientId}'
    scope     = 'https://api.azexecute.com/Standard.Access'
}
$deviceCode = $deviceCodeResponse.device_code
$verificationUrl = $deviceCodeResponse.verification_uri

# Step 2: User completes verification
# User must visit the verification URL and input the code shown on the device

# Step 3: Poll for the token
$tokenUrl = 'https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token'
$body = @{
    grant_type    = 'urn:ietf:params:oauth:grant-type:device_code'
    client_id     = '{clientId}'
    device_code   = $deviceCode
}
$response = Invoke-RestMethod -Uri $tokenUrl -Method Post -ContentType 'application/x-www-form-urlencoded' -Body $body
$accessToken = $response.access_token

An unhandled error has occurred. Reload 🗙