Getting started

The Partner API is a server-to-server HTTPS API on port 3020. It does not enable CORS and does not accept browser sessions, Bearer tokens, or legacy/mock credentials.

1. Check reachability

GET /health is the only public route. It checks the Partner process and database. It is outside the /v1 contract.

2. Obtain a credential

Partner credentials are managed by a human in the Academy control plane. Each credential belongs to exactly one club or federation workspace and uses either hmac-sha256 or rsa2 signing material.

P0 grant boundary

A credential can receive only scopes in its workspace catalog that the human issuer's Academy permissions allow. P0 explicitly defers subscription restrictions, so do not infer grants from a paid package, subscription status, module, rate or free-form flag. Unsupported issuer mappings and federation staff-only scopes remain refused. See Scopes.

3. Make a signed request

Every /v1 request is signed. Start with GET /v1/me; it requires authentication but no business scope. Follow the exact authentication canonical-string rules.

A successful response identifies the credential's workspace, public key id, label, scopes, and the legacy rate_limit informational field. Pace against the response X-RateLimit-* headers, not that field. The unprefixed RateLimit-* names remain compatibility aliases.

4. Use the reference

The API reference is generated from the same 95 decorated Partner operations published by the application. The one public health route is deliberately excluded. Club credentials receive 404 on federation routes and federation credentials receive 404 on club routes.

Successes are normally { "data": ... } with optional metadata. Errors use the flat shape documented under Errors. All identifiers in Partner payloads are decimal strings unless a schema says otherwise.