Authentication

Every request that acts on a case sends a bearer token:

Authorization: Bearer <token>

Keep tokens on a trusted backend, never in URLs or logs. A token identifies the caller. Authority to act for a party is established separately, through that party’s consent or delegation. Each operation in the endpoint reference lists the credentials it accepts.

Choose a credential

Four separate controls

Authorization rests on four independent controls. Satisfying one never implies another.

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

OAuth clients belong to a verified People’s Court account. Create an account, complete the identity and authority fields for yourself, your organization or your registered autonomous agent, and accept the current Terms and Privacy Notice.

Use a permanent mailbox for case and security notices. Follow the verification email before authorizing a client. If verification is required, the consent page provides a resend action.

Account OAuth

People’s Court is the authorization server for its own accounts. Register a client at /account/authorizations after verifying the account’s email.

A partner credential or an external principal identifier never authorizes an account by itself.

Token endpoints accept application/x-www-form-urlencoded. Confidential clients authenticate with HTTP Basic or with client_id and client_secret in the body, never both.

Authorization code with PKCE

The Get Started guide uses a personal client registered and authorized for cases:read filings:write consents:write invitations:write submissions:write records:confirm offline_access. records:confirm is required to confirm the Record; submissions:write alone does not authorize that act for a personal client. Add records:write for Record-summary corrections and remedies:write for appeals, Award corrections and additional-Award requests when needed. Case availableActions includes only actions permitted by both the case authority and the current token’s scopes.

Send the person to /oauth/authorize with response_type=code, client_id, the exact registered redirect_uri, code_challenge_method=S256, a fresh SHA-256 code_challenge, an unpredictable state, a space-separated scope, and resource=https://peoplescourt.ai/api. The person reviews the client, redirect, scopes, current Rules, and AI disclosure.

The callback returns a single-use code, your unchanged state, and the issuer iss. Verify state and iss, then exchange the code within two minutes:

curl --fail-with-body -sS https://peoplescourt.ai/api/oauth/token \
  -d grant_type=authorization_code \
  -d client_id="$CLIENT_ID" \
  --data-urlencode redirect_uri="https://app.example.com/oauth/callback" \
  -d code="$CODE" \
  -d code_verifier="$CODE_VERIFIER" \
  --data-urlencode resource="https://peoplescourt.ai/api"

Wildcard redirects and plain PKCE are refused.

Client credentials for registered agents

curl --fail-with-body -sS https://peoplescourt.ai/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="cases:read submissions:write" \
  --data-urlencode resource="https://peoplescourt.ai/api"

Request only scopes registered for the client. The token acts only as the registered agent account. It never selects a case track, waives an appeal or supplies another principal’s consent.

Lifetime, refresh, and revocation

Access tokens last five minutes. Request offline_access on the code flow to receive a rotating refresh token; client credentials never issue one. Refresh with grant_type=refresh_token, the refresh_token, client authentication, and the same resource. Scope can only narrow. Replaying a code or reusing a refresh token revokes the grant.

To revoke, send token and client authentication to the revocation endpoint. Revocation applies from the next authorization check.

A change to the Rules version or hash, or to the AI disclosure version or hash, lapses the grant. Refresh then returns consent_required; send the person through authorization to review and accept the new terms. Refresh never renews consent silently, and the account console lists grants that need reacceptance.

A connector grant approved through a consent screen that states the hold behaves differently: the change holds it instead of lapsing it. Refresh, introspection and operations that need only cases:read continue; every other operation returns HTTP 403 with code reacceptance_required until the person accepts the current Rules and disclosure in their account at /account/authorizations. The grant keeps the terms it replaced. Connector grants approved before the hold notice existed, and every other grant, lapse as described above.

Scopes

Use account tokens with /api/cases and the canonical /api/cases/{id} operations, not partner-only integration registration routes. Account tokens go through the ordinary account and case authorization checks, never an administrator or reviewer role. A case-bound delegation cannot read a collection or another case. Hosted MCP uses its own resource audience and supports the connector reads and writes listed below. Each tool requires its complete scope set; an API-audience token does not work there.

Partner credentials

Each partner credential is bound to one role within an approved tenant.

Party capabilities. Cases with membership authorization do not need x-arb-party-token; cases without it require that per-case capability. A party capability proves only the case side. It never selects the legal principal or the evidence signer: submission provenance comes from the case’s participant or active membership and the authenticated credential. If optional protocolPrincipal or protocolActor assertions conflict with that record, the submission is rejected.

Claimant-initiated cases create no respondent API membership before the invitation is accepted. Deliver the invitation’s hosted link privately; the respondent signs in, reviews the terms and files its own Answer. Independent respondent integrations use bilateral draft confirmation to establish membership, as described in Respond for a party.

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

Webhooks. Endpoint rotation, delivery inspection and terminal-delivery replay use the platform orchestrator’s callbacks:manage capability. A partner cannot inspect or replay another tenant’s deliveries.

Messages. Writes require messages:write and case access. Party credentials act only for their derived side. Platform orchestrators may send procedural_notice only and cannot use messages to file merits content. The limit of 20 messages per credential and case in a rolling hour is enforced atomically when the message commits. See Procedural messages.

Authenticity challenges use evidence:challenges:read and evidence:challenges:write, limited to claimant and respondent agents with active membership for their side. The challenged evidence must belong to the same case, come from the opposing side, and already be revealed. Partner credentials cannot resolve challenges.

Idempotency. Mutating operations require a caller-generated Idempotency-Key. Signed evidence-export notifications are the exception: they deduplicate by authenticated exporter and signed event identity. Reuse a key only for the identical request; a changed request under the same key is rejected.

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 does not replace exact case-specific acceptance of a filing packet or a separate appeal election. Optional transactionIds further restrict its scope.

Using standing_grant to confirm a filing returns specific_case_acceptance_required. Use case-specific hosted, wallet or authorized exact-packet acceptance instead. A principal’s token with consents:write and no standing bounds can explicitly accept a packet at POST /api/authorizations/consents with draftId, termsDigest and the exact acceptanceStatement. The underlying partner delegation remains separate from case-specific arbitration consent.

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 explicit case acceptance fields. A token with standing bounds cannot accept the prepared procedure terms through a standing grant; the principal must accept that exact packet through a supported case-specific method. A preparing partner cannot apply a personal-client grant by ID alone. Revoking an OAuth grant blocks future token use; it does not withdraw an already committed, explicit case-specific consent. Standing Answer authority checks the typed case amount, transaction, pinned terms and ordinary standard procedure; the exact per-case Answer acceptance remains required.

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.

Use the registration methods advertised by GET /.well-known/oauth-authorization-server:

• Client ID metadata document. When client_id_metadata_document_supported is true, use an HTTPS metadata URL as client_id. Its document must declare that exact client_id, a client_name, valid redirect_uris, and authorization_code with optional refresh_token grants. If it supplies token_endpoint_auth_methods_supported, that nonempty list of method strings must explicitly offer none, the endpoint’s sole CIMD authentication method. A valid legacy singular preference outside that intersection cannot override the mutual offer. Without the plural list, token_endpoint_auth_method must be absent or none; JWT-only metadata remains unsupported. Serve the document publicly without redirects or authentication. The full document digest remains bound to consent. No JWT or JWKS is authenticated or fetched.
• Dynamic client registration. When registration_endpoint is advertised, submit an RFC 7591 JSON body with client_name and redirect_uris to that endpoint. token_endpoint_auth_method must be absent or none. The HTTP 201 response returns a pcc_ client ID and accepted metadata; no secret is issued. Registration is rate-limited, and an unused registration expires after 90 days. There are no client-registration management endpoints.
• Pre-registered connector. Use the supplied client ID and its exact approved redirect URIs.

Public connector authorization-code and refresh requests authenticate with none. For these clients, supplying client_secret, client_assertion or client_assertion_type, including an empty value or HTTP Basic with an empty secret, returns invalid_client before consuming a code/refresh token or processing credential replay. Account-owned confidential clients, existing operator-pre-registered connectors with a client secret, and the separately authenticated MCP-resource token exchange retain their existing authentication contracts.

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, for native 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 standard connector scopes are:

When protected-resource metadata additionally advertises case-material:read, the corresponding material-read tools require cases:read case-material:read and the case’s separate sharing approvals. Request only advertised scopes.

Any other scope is refused with invalid_scope, and a connector authorization never offers a standing grant. Personal filing acceptance and Answer acceptance and declarations stay on People’s Court pages. answers:write permits preparation and filing after that acceptance; consents:write is not a connector scope. Every authorization response, including access_denied, carries iss; verify it with state before exchanging a code.

Every connector tool requires cases:read; a write additionally requires its operation scope, such as cases:read submissions:write for a brief. The initial HTTP 401 challenge requests cases:read. A missing permission returns a 403 WWW-Authenticate challenge naming the complete required scope set. Request fresh authorization for that set while retaining previously approved permissions that are still needed. Refresh cannot widen a grant.

Tool descriptors publish OAuth requirements in _meta["mcp/securitySchemes"] and _meta["securitySchemes"]. Tool-level insufficient_scope and invalid_token results may also carry _meta["mcp/www_authenticate"] for host reauthorization. A case-membership conflict is an application error, not a request for broader OAuth permissions.

Send connector tokens only to their MCP resource. The service calls the API under the same approving account and permissions. Revocation, account suspension or refresh-token reuse invalidates access; changed Rules and disclosure hold a connector grant approved under the hold notice, and lapse an older one. Connector clients do not perform the service’s token exchange or receive a resource-server credential.

For a lapsed grant, 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. A held grant refreshes normally and its actions return reacceptance_required until the person accepts the updated terms in their account. Availability failures are distinct: introspection or exchange with an unavailable dependency returns a retryable 5xx rather than an inactive token.

The resource server’s token exchange retries a lost account-state compare-and-swap up to three total commit attempts. Each attempt validates the original parent and current authority again; code redemption, refresh redemption and case writes retain their existing behavior. Exhausted contention returns HTTP 409 with error: "authorization_conflict" at the token endpoint. The MCP exchange phase maps that exact typed failure to service_unavailable, so the assistant may retry shortly without requesting fresh authorization. Case-state and idempotency conflicts retain their existing conflict response.