Authentication and authorization

Each request to an Azure AI service must include an authentication header. This header passes along a resource key or authentication token, which is used to validate your subscription for a service or group of services. In this article, you can explore ways to authenticate a request and the requirements for each.

• Authenticate with a single-service or multi-service resource key.
• Authenticate with a bearer token.
• Authenticate with Microsoft Entra ID.

Headers

Subscribe to Translator or multi-service in Azure AI services, and use your key (available in the Azure portal) to authenticate.

There are three headers that you can use to authenticate your subscription. This table describes how each is used:

Secret key

The first option is to authenticate using the Ocp-Apim-Subscription-Key header. Add the Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> header to your request.

Authenticating with a global resource

When you use a global translator resource, you need to include one header to call the Translator.

Here's an example request to call the Translator using the global translator resource

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

Authenticating with a regional resource

When you use a regional translator resource, there are two headers that you need to call the Translator.

Here's an example request to call the Translator using the regional translator resource

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

Authenticating with a multi-service resource

A multi-service resource allows you to use a single API key to authenticate requests for multiple services.

When you use a multi-service secret key, you must include two authentication headers with your request. There are two headers that you need to call the Translator.

Region is required for the multi-service Text API subscription. The region you select is the only region that you can use for text translation when using the multi-service key. It must be the same region you selected when you signed up for your multi-service subscription through the Azure portal.

If you pass the secret key in the query string with the parameter Subscription-Key, then you must specify the region with query parameter Subscription-Region.

Authenticating with an access token

Alternatively, you can exchange your secret key for an access token. This token is included with each request as the Authorization header. To obtain an authorization token, make a POST request to the following URL:

Here are example requests to obtain a token given a secret key for a global resource:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

And here are example requests to obtain a token given a secret key for a regional resource located in Central US:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

A successful request returns the encoded access token as plain text in the response body. The valid token is passed to the Translator service as a bearer token in the Authorization.

Authorization: Bearer <Base64-access_token>

An authentication token is valid for 10 minutes. The token should be reused when making multiple calls to the Translator. However, if your program makes requests to the Translator over an extended period of time, then your program must request a new access token at regular intervals (for example, every 8 minutes).

Authentication with Microsoft Entra ID

Translator v3.0 supports Microsoft Entra authentication, Microsoft's cloud-based identity and access management solution. Authorization headers enable the Translator service to validate that the requesting client is authorized to use the resource and to complete the request.

Prerequisites

• A brief understanding of how to authenticate with Microsoft Entra ID.

• A brief understanding of how to authorize access to managed identities.

Microsoft Entra ID headers

Translator property page—Azure portal

Examples

Using the global endpoint

// Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Using your custom endpoint

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Examples using managed identities

Translator v3.0 also supports authorizing access to managed identities. If a managed identity is enabled for a translator resource, you can pass the bearer token generated by managed identity in the request header.

With the global endpoint

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

With your custom endpoint

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Virtual Network support

The Translator service is now available with Virtual Network (VNET) capabilities in all regions of the Azure public cloud. To enable Virtual Network, See Configuring Azure AI services virtual networks.

Once you turn on this capability, you must use the custom endpoint to call the Translator. You can't use the global translator endpoint ("api.cognitive.microsofttranslator.com") and you can't authenticate with an access token.

You can find the custom endpoint after you create a translator resource and allow access from selected networks and private endpoints.

1. Navigate to your Translator resource in the Azure portal.

2. Select Networking from the Resource Management section.

3. Under the Firewalls and virtual networks tab, choose Selected Networks and Private Endpoints.

   

4. Select Save to apply your changes.

5. Select Keys and Endpoint from the Resource Management section.

6. Select the Virtual Network tab.

7. Listed there are the endpoints for Text Translation and Document Translation.

   

Here's an example request to call the Translator using the custom endpoint

// Pass secret key and region using headers
curl -X POST "https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"