Key and token-based authentication for online endpoints

When consuming an online endpoint from a client, you can use either a key or a token. Keys don't expire, tokens do.

Configure the endpoint authentication

You can set the authentication type when you create an online endpoint. Set the auth_mode to key or aml_token depending on which one you want to use. The default value is key.

When deploying using CLI v2, set this value in the online endpoint YAML file. For more information, see How to deploy an online endpoint.

When deploying using the Python SDK v2, use the OnlineEndpoint class.

Get the key or token

Access to retrieve the key or token for an online endpoint is restricted by Azure role-based access controls (Azure RBAC). To retrieve the authentication key or token, your security principal (user identity or service principal) must be assigned one of the following roles:

  • Owner
  • Contributor
  • A custom role that allows Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action and Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action.

For more information on using Azure RBAC with Azure Machine Learning, see Manage access to Azure Machine Learning.

To get the key, use az ml online-endpoint get-credentials. This command returns a JSON document that contains the key or token. Keys will be returned in the primaryKey and secondaryKey fields. Tokens will be returned in the accessToken field. Additionally, the expiryTimeUtc and refreshAfterTimeUtc fields contain the token expiration and refresh times. The following example shows how to use the --query parameter to return only the primary key:

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

Score data using the token

When calling the online endpoint for scoring, pass the key or token in the authorization header. The following example shows how to use the curl utility to call the online endpoint using a key (if using a token, replace $ENDPOINT_KEY with the token value):

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

Next steps