Azure AI Face Service: Fix Setup & API Errors

This is the step most developers skip because they don't expect it. The Azure AI Face service, specifically the face recognition, face identification, face verification, and liveness detection capabilities, is a limited access service. Microsoft restricts it to approved customers and partners as part of its Responsible AI framework. You cannot call these APIs on an unapproved subscription, no matter how correctly your code is written.

Here's how to check your status and fix it:

First, navigate to the Face Recognition intake form on the Azure website. This form asks for your organization name, use case description, and Azure subscription ID. Fill it out completely, vague use case descriptions get rejected or delayed. Be specific: "touchless check-in for hospital reception kiosks" is better than "access control."

Once you submit, Microsoft reviews the request. The review typically completes within a few business days, though enterprise customers with existing Microsoft relationships often get faster turnaround. You'll receive an email confirmation when your subscription is approved.

After approval, verify it's active by going to the Azure portal, opening your Face resource, and checking the Overview blade. You should see the resource status as Running with no policy blocks listed. If you see a yellow warning banner mentioning "limited access" or "policy restriction," your subscription either hasn't been approved yet or the approval hasn't fully propagated.

One important note from the official documentation: if you're working with biometric data, and face images absolutely qualify, you're responsible for providing appropriate notice to data subjects, obtaining consent, and deleting biometric data when required. This isn't just a legal footnote; Azure's terms enforcement around this has teeth. Make sure your application design accounts for it before you go live.

When this step is complete, a simple test call to the Detect endpoint should return a 200 response rather than a 403.

Authentication errors with the Azure AI Face service are almost always an endpoint or header formatting issue. Let me walk you through the exact setup.

In the Azure portal, open your Face resource. Under Resource Management, click Keys and Endpoint. You'll see:

• KEY 1 and KEY 2, both are valid subscription keys
• Endpoint, this is your resource-specific base URL

Your endpoint will look like this:

https://your-resource-name.cognitiveservices.azure.com/

When making REST API calls directly, pass your key in the Ocp-Apim-Subscription-Key header. Here's a working curl command to detect faces in an image URL:

curl -X POST \
  "https://your-resource-name.cognitiveservices.azure.com/face/v1.0/detect" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://upload.wikimedia.org/wikipedia/commons/c/c3/RH_Louise_Lillian_Gish.jpg"}'

If this returns a 200 OK with a JSON array, your keys and endpoint are fine. If you get a 401, your key is wrong. If you get a 403, your subscription isn't approved for Face access. If you get a 404, your endpoint URL is wrong or the resource doesn't exist in the region you specified.

For SDK users in C#, the initialization looks like this:

var client = new FaceClient(
    new ApiKeyServiceClientCredentials("YOUR_FACE_API_KEY"))
{
    Endpoint = "https://your-resource-name.cognitiveservices.azure.com/"
};

Note the trailing slash on the endpoint. Missing it causes a malformed request URL in some SDK versions. When this step succeeds, your SDK calls stop throwing HttpRequestException or UnauthorizedAccessException at initialization time.

Here's one that trips up even experienced Azure developers. The Azure AI Face service has multiple detection model versions, detection_01, detection_02, and detection_03, and they're not interchangeable with recognition models. When you call the Detect API without specifying a model, you get the default, which may not be what you need and can cause downstream failures when you try to use the resulting face IDs with recognition operations.

The official documentation is clear on this: you must specify both a detection model and a recognition model version when adding faces to a PersonGroup, and you must use the same detection model when you call Detect to identify faces against that PersonGroup later. Mixing them produces errors or, worse, silently incorrect match results.

Here's how to explicitly set the detection model in a REST call:

POST https://your-resource-name.cognitiveservices.azure.com/face/v1.0/detect
  ?detectionModel=detection_03
  &returnFaceId=true
  &returnFaceLandmarks=false

And when creating a PersonGroup:

PUT https://your-resource-name.cognitiveservices.azure.com/face/v1.0/persongroups/{personGroupId}
Content-Type: application/json
{
  "name": "MyGroup",
  "userData": "optional info",
  "recognitionModel": "recognition_04"
}

Use recognition_04 for new projects, it's the most accurate model available as of the current documentation. If you're migrating a PersonGroup built on recognition_03, you need to rebuild it with the newer model. There's no in-place upgrade path; the face data structures are incompatible between recognition model versions.

When this is correct, you stop seeing errors like FaceNotFound during identify operations even when you know the face was enrolled. That error almost always means a model version mismatch rather than an actual missing face.

Liveness detection is the anti-spoofing feature that determines whether a face in a video stream belongs to a real, physically present person, not a photo, a recorded video, or a 3D mask. If you're building an identity verification flow or touchless access control system, you almost certainly need this. And it has its own separate access gate.

Even if your subscription is already approved for the general Face service, liveness is handled separately. You need to submit the Face Recognition intake form again and specifically request liveness access. Once approved, you can download the Face liveness SDK, it's not available on public NuGet, npm, or PyPI. You download it directly after your subscription is approved.

For the server-side session management, liveness detection works through a session model. Your backend creates a liveness session and receives a session authorization token. Your frontend client (mobile app or web app using the SDK) uses that token to run the liveness check with the user's camera. Your backend then queries the session result. The face never travels to your server; only the verification result does.

Here's the session creation REST call pattern:

POST https://your-resource-name.cognitiveservices.azure.com/face/v1.0-preview.1/detectLiveness/singleModal/sessions
Ocp-Apim-Subscription-Key: YOUR_KEY
Content-Type: application/json
{
  "livenessOperationMode": "Passive",
  "deviceCorrelationId": "device-unique-id-here",
  "sendResultsToClient": false
}

The response includes a session ID and an authToken. Pass the authToken to your frontend SDK, never the subscription key. This design ensures your main API credentials stay server-side only.

If the liveness SDK throws LivenessSessionNotFound or InvalidAuthToken, check that the token hasn't expired (default lifetime is 10 minutes) and that you're passing the token, not the subscription key, to the client SDK. This is the most common liveness setup error I see.

This one catches teams mid-project. If your application previously called the Face Detect API and requested emotion or gender attributes, those requests now return errors or empty results. Microsoft officially retired the emotion detection and gender estimation capabilities in 2023, citing the risk of misuse and stereotyping. They're gone. There's no flag to re-enable them, no workaround, no legacy endpoint that still serves them.

The limited capabilities, age estimation, smile detection, facial hair detection, hair color, and makeup detection, are still available but only to approved use cases. If your application needs any of these, email the Azure Face team directly (the address is in the official Azure Face documentation) with a description of your responsible use case.

To check which attributes you're currently requesting in your detect calls, look at your returnFaceAttributes parameter:

GET https://your-resource-name.cognitiveservices.azure.com/face/v1.0/detect
  ?returnFaceAttributes=age,smile,headPose,glasses,occlusion,accessories,blur,exposure,noise

In the list above, age and smile are limited, they require approval. The others (headPose, glasses, occlusion, accessories, blur, exposure, noise) are generally available without special approval and are safe to use in production. If your detect calls are returning a 400 Bad Request with a message about unsupported attributes, remove emotion and gender from your attribute list immediately. That will unblock the call.

Going forward, architect your application around the supported attributes and design your user flows so that face data quality (blur level, head pose, occlusion) guides your enrollment process rather than inferring personal characteristics. This is both better practice and more reliable technically, the quality metrics are objective measurements, while the retired attributes were probabilistic guesses that introduced real risks.

Once you've cleaned up your attribute requests, your detect calls should return a clean 200 with a well-structured JSON face object containing the face rectangle, face ID, and the approved attributes you requested.