docs: clarify SCRAPI v09 API-review responses and compatibility boundaries

[Copilot]

As requested, this PR adds a concise, review-ready response to the SCRAPI draft-09 API review questions directly in project documentation.

The problem raised was not missing implementation, but ambiguity around how draft-09 behavior coexists with legacy clients. This update makes those compatibility rules explicit and easy to reference.

• Documentation update

  • Expanded docs/scitt.md with an “API review clarifications (SCRAPI draft 09)” section.

• Version-gated behavior clarified

  • Documents that draft-09 behavior is enabled via api-version=2026-03-26.
  • States that absent/unknown versions retain legacy behavior.

• Endpoint surface clarified

  • Distinguishes standard draft-09 key endpoints:
    • /.well-known/scitt-keys
    • /.well-known/scitt-keys/{kid_value}
  • Explicitly calls out retained legacy endpoints for backward compatibility (/jwks, /.well-known/transparency-configuration).

• Registration/polling semantics clarified

  • Captures SCRAPI async flow (POST /entries → 303 + /entries/{txid} locator).
  • Captures pending/complete polling responses on /entries/{txid} (302 pending, 200 completed).
  • Captures legacy async flow (202 + /operations/{txid}).

• Media type expectations clarified

  • Documents SCRAPI content types:
    • application/scitt-receipt+cose
    • application/scitt-statement+cose
  • Notes legacy application/cose behavior.

• Non-normative extension endpoints enumerated

  • Adds an explicit list of implementation-specific endpoints kept outside the draft-09 mandatory API surface.

# SCRAPI v09 (api-version=2026-03-26)
POST /entries                  -> 303 See Other
Location: /entries/{txid}

GET /entries/{txid}            -> 302 Found (pending) | 200 OK (receipt)
Content-Type: application/scitt-receipt+cose

# Legacy compatibility
POST /entries                  -> 202 Accepted
Location: /operations/{txid}

GET /operations/{txid}         -> legacy polling behavior

Original prompt

recently we update scitt according to draft-ietf-scitt-scrapi-09 - SCITT Reference APIs after api review they rasise some question to answer. can you help me to reply

Created from VS Code.

[ryazhang-microsoft]

@copilot answer question dont need do any code question

[ryazhang-microsoft]

@copilot - API Changes and Long-Running Operation Pattern: Clarify with the team the rationale for the new long-running operation pattern and whether it is necessary given the operation's response time, and provide feedback to the group. (Ryan)

• API Endpoint Usage and Documentation: Consult with the team to clarify the purpose and usage of the new key-related endpoints (well-known/key and KID), and provide detailed information on their intended use cases and expected responses. (Ryan)
• Error Response Codes and Aliases: Check with the team to explain the reasoning behind the introduction of the new 401 error response and the creation of a new alias for V09, and communicate the findings to the group. (Ryan)
• Transaction/Request ID Header Naming: Discuss with the team whether to use XMS Request ID instead of CCF Transaction ID for failed request identification, and ensure the documentation clearly explains the chosen field. (Ryan)