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.

On the option to retrieve the token via REST API, see Invoke the endpoint to score data with your model.

To get the key or token, 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. The following example shows how to use the --query parameter to return only the primary key:

ENDPOINT_CRED=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)

Tokens will be returned in the accessToken field:

ENDPOINT_CRED=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)

Additionally, the expiryTimeUtc and refreshAfterTimeUtc fields contain the token expiration and refresh times.

Score data using the key or 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/token:

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

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

Next steps