Documentation: non-compliant authentication example and stale content in click-to-dial_API.md

[hdamker]

Problem description

The supplementary API documentation documentation/API_documentation/click-to-dial_API.md contains an authentication example that is not compliant with the CAMARA Security & Interoperability Profile, together with some stale or inconsistent items. The normative OpenAPI definition (code/API_definitions/click-to-dial.yaml) is correct — these findings are limited to the documentation asset.

1. Authentication example uses a client-authentication method CAMARA does not permit

Section 2.1 ("Prerequisites") documents token acquisition as:

curl -X POST "{openid_token_url}" -d "grant_type=client_credentials&client_id={your_id}&client_secret={your_secret}"

The client_secret is the problem. The CAMARA Security & Interoperability Profile requires the API Consumer to authenticate to the authorization server using private_key_jwt (a signed JWT client assertion) — for all flows, including the Client Credentials flow. A shared client_secret (client_secret_basic / client_secret_post) is not an accepted client-authentication method in CAMARA:

"The API Consumer MUST authenticate with the Authorization server using private_key_jwt" — CAMARA Security & Interoperability Profile, Client Authentication.

(The grant type shown — Client Credentials, a two-legged token — is a separate matter: per the profile it may be used "only if agreed between the API Consumer and the API provider" for the declared purpose, so the documentation should not present any single grant type as the default.)

2. Stale and inconsistent content

• Section 4.1 states API Version: wip, and Section 4.9 states the current version is wip — this asset ships as 0.2.0-rc.1.
• Section 4.9 "Release Notes" lists only 0.1.0-alpha.1, omitting 0.1.0 (r1.4) and 0.2.0-rc.1.
• Section 4.2.3 "Click to Dial Initiation Request" attribute table omits recordingEnabled, which is part of CreateCallRequest and appears in the document's own examples.
• The "CloudEvent delivery notes" state the event MUST include datacontenttype, but CloudEvent.required in the OpenAPI lists only id, source, specversion, type, time. The documentation should not be stricter than the specification.
• The CloudEvent example uses identical caller and callee (+12345678), which the SAME_CALLER_CALLEE (422) rule forbids. The same example appears in the OpenAPI CALL_STATUS_CHANGED_EXAMPLE and should be corrected there too.

Expected action

• Replace the Section 2.1 / Section 3 authentication example so client authentication uses private_key_jwt (a client_assertion signed JWT), not client_id / client_secret. Present token acquisition as agreed at onboarding rather than hard-coding a grant type, and reference the OpenAPI security scheme and required scopes.
• Refresh the version placeholders (wip → 0.2.0-rc.1) and the Release Notes list. Note that supplementary documentation files are not updated automatically by Release Automation — either maintain these version references manually for each release, or avoid embedding version numbers in the documentation.
• Add recordingEnabled to the request attribute table.
• Align the datacontenttype statement with CloudEvent.required (make it non-mandatory), and correct the caller/callee example in both the document and the OpenAPI CALL_STATUS_CHANGED_EXAMPLE.

Additional context

• Identity and Consent Management — CAMARA Security & Interoperability Profile, Client Authentication (mandates private_key_jwt): https://github.com/camaraproject/IdentityAndConsentManagement/blob/r4.2/documentation/CAMARA-Security-Interoperability.md#client-authentication
• CAMARA API Design Guide — the OpenAPI definition is the authoritative source of truth and supplementary documentation must not contradict it: https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md
• Affected files: documentation/API_documentation/click-to-dial_API.md; the example correction also applies to code/API_definitions/click-to-dial.yaml (CALL_STATUS_CHANGED_EXAMPLE).

[YadingFang]

Thanks @hdamker. The issues identified here have been addressed in draft PR #115. The PR updates the authentication guidance and aligns the supplementary documentation and examples with the OpenAPI definition.