Provider API Authorization Process Prompt

This document provides a reusable prompt template to generate a provider-facing authorization guide for the Provider API. It is designed for OAuth 2.0 client credentials with Microsoft Entra-issued JWTs and the current Data Service runtime validation rules.

Purpose

Use this prompt when you need a consistent, complete explanation of how a provider must authenticate and authorize calls to:

• POST /api/provider/v1/controls

Prompt Template

Copy and adapt the prompt below.

Create a provider-facing authorization guide for the Kontrolle+ Provider API.

Audience:
- External provider technical teams integrating machine-to-machine API access.

Environment context:
- Environment name: <ENV_NAME>
- API base URL: <API_BASE_URL>
- Authority (issuer base): <AUTHORITY>
- Token endpoint: <TOKEN_ENDPOINT>
- API audience expected by backend (`aud`): <API_AUDIENCE>
- Token scope for acquisition: <API_SCOPE_DEFAULT>
- Required app role claim: ProviderApi.Access
- Optional allowed client IDs enforcement: <ALLOWED_CLIENT_IDS_ENABLED true|false>

Implementation rules that must be reflected exactly:
1. Access token must be obtained via OAuth 2.0 client credentials.
2. Requests must include `Authorization: Bearer <access_token>`.
3. Backend accepts token only when issuer matches configured authority.
4. Backend accepts token only when audience matches configured audience.
5. Token must include `roles=ProviderApi.Access`.
6. If allowed client ID filtering is enabled, token client identity (`azp` or `appid` or `client_id`) must match configured allow-list.
7. `X-Provider-Id` is optional and used only for tracing/correlation, never for authentication.

Required output format:
- Section 1: Authorization architecture overview (provider client, Entra token service, Data Service validation).
- Section 2: Step-by-step onboarding checklist (registration, role assignment, credential delivery, validation).
- Section 3: Token acquisition request example (`grant_type=client_credentials`, `scope=<app-id-uri>/.default`).
- Section 4: API call example with bearer token.
- Section 5: Token validation matrix (claim/check/result).
- Section 6: Common failure cases and fixes:
  - 401 invalid issuer
  - 401 invalid audience
  - 403 missing role
  - 403 client ID not allowed
- Section 7: Security and operations best practices:
  - one client app per provider
  - secret/certificate rotation
  - least privilege
  - auditability and revocation model

Constraints:
- Keep guidance implementation-accurate to current backend behavior.
- Use clear operational language for provider teams.
- Do not describe delegated user flows.
- Focus only on machine-to-machine authorization.

Expected Claims and Header Rules

The generated guide should clearly communicate:

• Required auth header:
  • Authorization: Bearer <access_token>
• Optional tracing header:
  • X-Provider-Id: <provider_name>
• Required token role:
  • ProviderApi.Access
• Provider identity claim resolution order used by service:
  1. azp
  2. appid
  3. client_id
  4. X-Provider-Id
  5. unknown-provider

Quick Runtime Validation Checklist

Before handing credentials to a provider, verify all items:

1. Token is issued by configured ProviderJwt:Authority.
2. Token aud equals configured ProviderJwt:Audience.
3. Token includes role ProviderApi.Access.
4. If configured, token client identity matches ProviderJwt:AllowedClientIds.
5. Provider can successfully call:
   • POST /api/provider/v1/controls

Source References

• documentation/v2/api/09_PROVIDER_AUTH_ONBOARDING_GUIDE.md
• documentation/v2/api/16_PROVIDER_API_NOVA_DATA_MAPPING.md
• openapi/provider-controls.openapi.yaml
• services/data-service/Program.cs
• services/data-service/Controllers/ProviderControlsController.cs