RAG Service
API Docs Center
← Back to Documentation Center

Authentication

All API requests must include both of the following headers:

  • Ocp-Apim-Subscription-Key: <your-key> (subscription key, provided by your API administrator)
  • Authorization: Bearer <access_token> (JWT bearer token issued by Microsoft Entra ID / Azure AD)

Both are required for every call. Requests missing either header will be rejected with a 401 Unauthorized error.

For a step-by-step APIM + Entra ID JWT authentication setup, see APIM + Entra ID JWT Setup.

See the security guide in docs/security/APIM-EntraID-JWT-Setup.md for full setup details, including how to obtain a valid JWT and configure APIM policies.

Example request

curl

curl -s -X GET "https://<your-apim-host>/api/v2/health" \
    -H "Authorization: Bearer <access_token>" \
    -H "Ocp-Apim-Subscription-Key: <subscription-key>"

PowerShell (Windows)

$headers = @{
    Authorization = "Bearer <access_token>"
    "Ocp-Apim-Subscription-Key" = "<subscription-key>"
}
Invoke-RestMethod -Method GET "https://<your-apim-host>/api/v2/health" -Headers $headers

Token and key details

  • The JWT must be issued for your API App registration (audience: api://<app-id>) and may require the Api.Access role.
  • The subscription key is mapped to your APIM product; contact your admin if you do not have one.
  • For client credentials, request scope api://<app-id>/.default.

Common errors & troubleshooting

  • 401 Unauthorized: Missing or invalid subscription key
    • Add Ocp-Apim-Subscription-Key header or verify the key is active and mapped to the APIM product.
  • 401 Unauthorized: JWT validation failed
    • Ensure Authorization: Bearer <token> is present
    • Verify token audience (aud) matches your API (e.g., api://<app-id>) and issuer (iss) is correct
    • Confirm required roles/claims (e.g., roles includes Api.Access) if enforced
  • 403 Forbidden: Insufficient privileges
    • The token is valid but lacks required roles or app permissions. Update app role assignments or API permissions.
  • 429 Too Many Requests / 5xx from backend
    • Respect rate limits; check APIM/Backend health and logs

Security notes

  • Never place tokens or keys in URLs; use headers only
  • Keys and tokens may be masked in logs (rag_api_core/utils/logging_security.py scrubs sensitive values)
  • Rotate keys regularly; prefer JWT + Entra ID for stronger, role-based auth

See also

  • Security setup: docs/security/APIM-EntraID-JWT-Setup.md
  • OpenAPI security schemes (JWT + Ocp-Apim-Subscription-Key) are defined in the app factory and OpenAPI docs