AUTH4D-2 shared API and protocol contracts

These schemas define the wire shapes; this fragment does not enable any routes. Until an owning feature ticket implements a route, it remains unavailable/501.

Customer authentication

• GET /t/{tenantId}/.well-known/openid-configuration returns OidcDiscoveryDocument.
• GET /t/{tenantId}/.well-known/jwks.json returns JwksResponse with public RS256 keys only.
• GET /oauth/authorize accepts AuthorizationRequest: response_type=code, exact redirect_uri, state, code_challenge, code_challenge_method=S256, and scope including openid. Success redirects with code and state; failures use OAuthErrorResponse.
• POST /oauth/token accepts one TokenRequest variant: authorization_code, refresh_token, or urn:ietf:params:oauth:grant-type:device_code. Success returns TokenResponse; failures use OAuthErrorResponse. Implicit and password grants are unsupported.
• POST /oauth/revoke accepts TokenRevocationRequest and returns an empty success response; GET /oauth/userinfo returns UserInfoResponse for a valid access token with the required scopes.
• POST /t/{tenantId}/email/verification/start accepts EmailVerificationStartRequest; POST /t/{tenantId}/email/verification/confirm accepts EmailVerificationConfirmRequest and returns an IdentityProofResponse receipt. Generic start responses prevent account enumeration.
• GET /t/{tenantId}/identity/discord/start accepts DiscordAuthorizationStartRequest; the provider returns to /t/{tenantId}/identity/discord/callback with DiscordCallbackQuery. Callback state is one-time and browser-flow-bound.
• POST /t/{tenantId}/guest accepts GuestCreateRequest and returns GuestCreateResponse; POST /t/{tenantId}/guest/upgrade accepts GuestUpgradeRequest and returns GuestUpgradeResponse. The upgrade proof must belong to the same tenant, client, flow, purpose, and guest user.
• POST /device/authorization accepts DeviceAuthorizationRequest and returns DeviceAuthorizationResponse; POST /device/approval accepts DeviceApprovalRequest and returns DeviceApprovalResponse. Native clients redeem through the device-code token request.

Management and console

• GET /management/tenants returns ManagementTenantListResponse; POST /management/tenants accepts CreateTenantRequest and returns ManagementTenantResponse.
• GET /management/tenants/{tenantId}/clients returns ManagementClientListResponse; POST /management/tenants/{tenantId}/clients accepts CreateClientRequest and returns CreateClientResponse. A confidential client secret, when returned, is shown once and cannot be retrieved later.
• PUT /management/tenants/{tenantId}/clients/{clientId} accepts UpdateClientRequest and returns ManagementClientResponse; list responses use ManagementClientListResponse.
• Every management route requires a ManagementActor from the immutable control-plane realm and checks its route scope (tenant:read/write, client:read/write, etc.). Errors use ManagementErrorResponse; the console browser only calls its /api/* BFF and never handles the management credential.

X-Request-Id is server-generated and stable through response/error/audit handling; inbound values are ignored. OAuth errors remain protocol-shaped and are correlated through the response header; management errors carry request_id in their envelope. All schemas reject unknown fields where accepting them could blur security-sensitive policy.

See the architecture and security contracts (repository file docs/architecture/security-contracts.md) for service ownership, storage authority, trust boundaries, default expiries, and abuse budgets.