Cross-site API reference

The complete machine-readable contract is the OpenAPI 3.1 document openapi.yaml. It is rendered below; you can also open it as a full-page reference with more room, or import the file into Postman, Insomnia, or an OpenAPI client generator.

For how the two layers fit together (OAuth machine identity + the owner's per-kind/per-item consent) and the threat model, see Cross-site API: design and threat model. For a step-by-step two-site setup, see Client-server configuration.

Authentication at a glance

• Machine identity: every /pdv-api/* data call carries an OAuth2 bearer token from the client-credentials grant at /oauth/token. The token says which consumer is calling, nothing about a user.
• Per-user authorization: within that identity, access to a user's items is gated by per-kind trusts and per-item grants. Read and write are orthogonal - a write authorization does not confer read.
• Addressing: users are addressed by an opaque handle the consumer obtains by completing the consent ceremony once; never by uid.