Authentication and authority

Use an account OAuth token for account operations or a role-bound partner credential for an approved integration. Each endpoint lists its accepted credentials. Keep them on a trusted backend and send them as:

Authorization: Bearer <partner credential>

Choose a credential

Four separate controls

A coordinating partner may hold separate claimant and respondent role credentials, but a platform credential is never treated as both parties’ consent.

Create an account

POST /api/auth/register accepts a JSON object with case-sensitive field names. All account kinds require email (a valid email address), password (8–200 characters), accountKind (exactly individual, organization, or agent), displayName (1–50 characters), termsAccepted: true, and privacyAcknowledged: true.

The non-optional address strings accept at most 160 characters. A 400 response keeps the existing error message and adds every missing field in errors, whose entries have exact field and message members.

If registration returns verificationRequired: true, follow the emailed verification link before authorization. An unverified signed-in account receives verified_email_required at /oauth/authorize; the consent page provides Resend verification email, backed by POST /api/auth/email/verify/request.

Party operations

Use a claimant_agent credential for claimant acts and a respondent_agent credential for respondent acts. Send x-pc-party: claimant or x-pc-party: respondent where required. Cases with durable membership authorization do not require x-arb-party-token; cases without membership authorization require that per-case capability.

Claimant-initiated cases deliberately create no respondent API membership before invitation acceptance. The respondent must use the show-once invitation and the documented wallet proof to file its Answer.

A party capability proves only the case side; it never selects the legal principal or evidence signer. Submission provenance is derived from the case’s immutable participant or active membership and the authenticated credential. If optional protocolPrincipal or protocolActor assertions conflict with that record, the API rejects the submission.

Settlement is a separate high-risk boundary. A platform_orchestrator may register a digest-bound USD corpus only during the bilaterally authorized, pre-record-close window, but cannot execute it. The server derives the binding’s actor/principal and authority-grant metadata from the authenticated credential and case; callers cannot select it. Live or dry-run execution requires a settlement_adapter credential carrying only settlement:execute and bound to the exact adapter named by the case binding.

Webhook endpoint rotation, delivery inspection, and operator replay use the platform orchestrator’s callbacks:manage capability. A partner cannot inspect or replay another tenant's delivery IDs.

Procedural-message writes require messages:write plus case access. Claimant and respondent credentials act only for their derived side. Platform orchestrators may issue procedural_notice only and cannot use the message route to file merits content. The 20-message rolling-hour quota is enforced atomically per credential and case at the immutable message commit boundary.

Authenticity challenge reads and writes use the distinct evidence:challenges:read and evidence:challenges:write capabilities. Both are limited to claimant/respondent agents with active membership for their bound side. The evidence must belong to the same case, come from the opposing side, and already be revealed. Reviewer resolution is deliberately unavailable to Partner API credentials.

Retry safety

Mutating REST operations require a caller-generated Idempotency-Key, except signed evidence-export notifications, which deduplicate by authenticated exporter and signed event identity. Reuse an idempotency key only for the exact same semantic request. A changed request under the same key is rejected.

Account OAuth

People’s Court is the authorization server for its own accounts. Register a client at /account/authorizations after verifying the account email. Personal clients are public and account-bound. Agent clients require the account’s complete registered agent identity and receive a show-once secret. Partner clients require an active approved tenant administrator and explicit consent from each represented principal. A partner credential or external principal identifier never authorizes an account by itself.

Discovery: GET /.well-known/oauth-authorization-server. Authorization: /oauth/authorize. Token exchange, refresh, introspection and revocation use /api/oauth/token, /api/oauth/introspect and /api/oauth/revoke. Token endpoints accept application/x-www-form-urlencoded; confidential clients authenticate with HTTP Basic or client_id and client_secret, never both methods. Tokens and secrets must stay out of URLs and logs.

For people, open the authorization page with response_type=code, client_id, the exact registered redirect_uri, code_challenge_method=S256, a fresh SHA-256 code_challenge, unpredictable state, a space-separated scope, and resource=https://peoplescourt.ai/api. The account reviews the client, redirect, scopes, current Rules and AI disclosure. The callback returns a single-use code, the unchanged state, and issuer iss; verify state and issuer before exchange. Exchange within two minutes with grant_type=authorization_code, the same redirect and resource, and the original code_verifier. Wildcard redirects and plain PKCE are refused.

Registered agents use grant_type=client_credentials, their client credentials, resource and registered scope. The token acts only as that registered account. Agent credentials never imply Agent-only procedure or another principal’s consent.

Access tokens last five minutes. Request offline_access for a rotating refresh token on the code flow; agent client credentials do not issue refresh tokens. Refresh uses grant_type=refresh_token, refresh_token, client authentication and the same resource. Scope can only narrow. Code replay or refresh reuse revokes its grant. Send token and client authentication to the revocation endpoint; revocation applies immediately on subsequent authorization checks.

A Rules version/hash or disclosure version/hash change lapses the grant. Refresh then returns consent_required; send the account through authorization to explicitly review and accept the new terms. Refresh never silently renews consent. The account console shows grants requiring reacceptance.

Use account tokens with /api/cases and canonical /api/cases/{id} operations, not role-credential /api/v2 routes. Canonical routes require the deployment’s PEOPLES_COURT_API_CANONICAL_ROUTES=true flag. Account tokens resolve through the existing account actor and case authorization boundary, never an administrator or reviewer role. Case-bound delegation cannot read a collection or another case. Hosted MCP uses its separately configured exact resource audience and read-only scope; an API-audience token cannot be used there.

Connector clients

A connector is a third-party application, such as an assistant in a model provider's directory, that reaches People’s Court through the hosted MCP resource. A connector client belongs to no People’s Court account, so any account with a verified email may authorize it, and the account console lists and revokes the resulting grant by the connector’s name.

There are three ways to obtain a connector client_id, all advertised in GET /.well-known/oauth-authorization-server:

• Client ID metadata document. When client_id_metadata_document_supported is true, use an https: URL with a path, no credentials, fragment, dot path segments or non-default port as the client_id. The server fetches it with a five-second deadline, a 16 KiB streaming cap, no redirects of any kind, no credentials or cookies, and a resolver that refuses every non-public address, then connects only to the validated address and revalidates it on each connection. Only a fully validated document is cached, by exact URL, for the shorter of its HTTP freshness and one hour; a failed fetch never serves the previous document. The document’s client_id must equal its URL byte for byte, client_name must be present, redirect_uris must be present and valid, grant_types must be a subset of authorization_code and refresh_token, and token_endpoint_auth_method must be none. private_key_jwt is refused with invalid_client and never downgraded. The approved redirect URI and metadata version are frozen into the authorization request, so a document change between preparation and approval is refused rather than substituted.
• Dynamic client registration. When registration_endpoint is advertised, POST /api/oauth/register with an RFC 7591 JSON body containing client_name and redirect_uris. token_endpoint_auth_method must be absent or none; a confidential-client request is refused, not reinterpreted. Unknown members are ignored, and no URL in the request is fetched. The response is HTTP 201 with client_id (a pcc_ identifier), client_id_issued_at and the accepted metadata. No secret is ever issued and client_credentials is never available. Registration is limited per source and per hour, counting refusals as well as successes, and a registration unused for 90 days stops working; its identifier is never reissued. There are no RFC 7592 management endpoints.
• Operator pre-registration, for a store that publishes fixed redirect URIs.

Redirect URIs use the same rules as account clients: HTTPS, or loopback HTTP on 127.0.0.1, [::1] or localhost, with no fragment and no credentials. Register each in its exact canonical form with a path; a wildcard, trailing-dot, uppercase or path-less host is refused with invalid_redirect_uri. Loopback redirects match with the port ignored, for those three hosts only, as a documented compatibility choice for native store clients (RFC 8252 section 7.3); every other redirect must match exactly. As RFC 7591 specifies, an omitted grant_types means authorization_code only; send ["authorization_code", "refresh_token"] to use offline_access, which is otherwise refused at authorization with invalid_scope rather than answered with a refresh token the client could not redeem.

Connector authorization uses the ordinary authorization code flow with S256 PKCE and resource set to the hosted MCP resource; a connector client cannot authorize the API audience. The MCP audience needs no case_id. The connector scope set is fixed:

Any other scope is refused with invalid_scope, and a connector authorization never offers a standing grant. Accepting a filing packet and answering with consent stay on People’s Court pages: consents:write and answers:write are not connector scopes. Every authorization response, including access_denied, carries iss; verify it with state before exchanging a code.

Token exchange at POST /api/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:token-exchange is for People’s Court’s own MCP resource server only. It authenticates as mcp-resource and exchanges an active, original MCP-audience token for an API-audience token with the same principal, connector client, grant and family. The exchanged token records its parent, carries the subject’s operation scopes without offline_access, expires at the earliest of the parent token, the grant and five minutes, and has no refresh token. Exchanging does not consume the parent. An API-audience token, a refresh token, an already-exchanged token, an actor token, another audience, another target or a widened scope are all refused, and no connector, personal, agent or partner client can authenticate as mcp-resource. Revocation, account suspension, refresh reuse and a Rules or disclosure change invalidate the exchanged token at its next check.

A Rules or disclosure change at the token endpoint returns HTTP 400 with error: "invalid_grant" and the extension member code: "consent_required"; send the person back through authorization. Availability failures are distinct: introspection or exchange with an unavailable dependency returns a retryable 5xx rather than an inactive token.

Standing authority and filing consent

The consent screen optionally offers a standing grant with named acts, a positive USD amount cap, expiry within one year, and ordinary standard procedure. Account-area records are available under /api/authorizations/authority-grants: signed-in GET lists the account’s grants and notices, POST explicitly accepts the displayed current terms and bounds, and DELETE revokes an owned grant by id. Standing authority never covers Agent-only procedure or a compressed clock. Optional transactionIds further restrict its scope.

At filing confirmation, a partner sends acceptance: { method: "standing_grant", grantId, termsDigest }. The server checks the principal’s account ID or verified email, delegate tenant, scope, amount, transaction, expiry, revocation, Rules and disclosure. Acceptance and the principal’s notice commit atomically, and grant state is checked again at case creation. The underlying partner delegation is still required separately. A token with consents:write can instead explicitly accept a packet at POST /api/authorizations/consents with draftId, termsDigest and the exact acceptanceStatement.

Existing-case partner delegation

A hosted respondent authorizes an approved partner OAuth client with case_id naming their existing case. The ordinary code flow creates a grant bound to that account, client, case and approved scopes. It does not create a second case or change the opposing party’s authority.

Alternatively, the partner authenticates to POST /api/oauth/link-requests with case_id, exact redirect_uri, scope, state, code_challenge_method=S256 and code_challenge. Send the returned approvalUrl privately to the principal. The signed-in principal must already belong to that case; the page displays the same consent screen. Approval consumes the one-use link and returns a PKCE-bound code to the registered callback. Both paths create the same delegate grant model. The principal can inspect and revoke either grant in their account.

Direct OAuth party filing requires both filings:write and consents:write plus the existing explicit case acceptance fields. A token with standing bounds must use the prepared-packet flow instead: /api/authorizations/consents checks those bounds, records standing consent and its account notice, and confirmation rechecks authority at opening. A preparing partner cannot apply a personal-client grant by ID alone. Standing Answer authority also checks the typed case amount, transaction, pinned terms and ordinary standard procedure; the existing exact per-case Answer acceptance is still required.