Status. Proposed design only. Nothing in this vault is GGA client approval. The GGA client documents are supplied drafts: see GGA-Source-Digest. No application, service or test has been executed; every scenario is Not executed. Delivery fees and dates are open.
API contract and request pipeline
Sources: Blueprint pp. 14 to 15 (GGA-Requirement-Register). Versioned endpoints with one set of server-side rules for the web interface, integrations and the operations console. Paths are a reference contract; the developer supplies an OpenAPI contract with examples for every endpoint, including correction, withdrawal, cancellation and administration actions.
flowchart LR A[Authenticate session] --> B[Resolve membership<br/>selected company context] --> D[Authorise record<br/>role, ownership, grant] --> E[Validate version and transition<br/>commit mutation, audit, event] C[Evaluate eligibility at request time] -.only where the endpoint needs it.-> D
Public endpoints skip authentication. The eligibility check is endpoint-dependent: detailed discovery, new interests, new introductions and new event registrations need it; an incomplete or overdue company can still reach its own profile, correction guidance, introduction history, outcomes and contribution records (Blueprint p. 3).
| Endpoint group | Required contract |
|---|---|
GET /v1/public/opportunities | Paginated approved summaries only, country and category filters; no private field in HTML, JSON, metadata or cache |
POST /v1/companies, /v1/company-invites | Company draft or owner-authorised colleague invite; verified identity, duplicate checks, invitation expiry |
GET/PATCH /v1/company/profile | Current membership and expected_version; structured missing-field errors |
POST /v1/company/attestations | Confirm a specific complete version; recalculate due date and eligibility atomically |
GET /v1/opportunities/{id} | Member projection only when eligible and active; restricted fields need a separate valid grant |
POST /v1/opportunities, /{id}/submit | Create or submit an owned listing version; partner approval or eligible company status; submission does not publish |
POST /v1/reviews/{id}/decision | Operations only; approve, request changes, reject or hold with reason and expected_version; rebuild only the approved public projection |
POST /v1/opportunities/{id}/interests | Eligible company, active unexpired offer, scoped pitch; one open interest; matching retry returns the existing result |
POST /v1/interests/{id}/decision, /v1/introductions/{id}/consents | Only the listing owner decides; only each participant consents; final transaction re-checks both current consents bound to introduction, recipient, fields and files, purpose, version and expiry, both users’ authorisation, the active listing and the applicant’s eligibility, then creates the release record, grants and notifications once. Owner acceptance also confirms ownership and an active offer |
POST /v1/events/{id}/registrations | Eligibility, capacity and uniqueness in a transaction; explicit cancellation and waitlist promotion |
POST /v1/outcomes, /v1/contribution-opt-ins | Outcomes belong to the reporting company; an authorised owner confirms value before accepting a versioned contribution offer |
POST /v1/finance/invoices, /settlements | Finance role only; approve totals, reconcile, activate a term once; a partial, disputed or mismatched payment stays a finance exception; voids, refunds and corrections carry reasons; webhooks verify signature and transaction identity |
GET /v1/files/{id}/download | Owner or grantee, resource version, scan state, grant expiry; authorised handler or short-lived link; never expose storage keys |
Response rules
Return a request ID, typed result and resource version. 401 unauthenticated; 403 prohibited; 404 where resource existence must stay private; 409 stale version or invalid state; 422 validation; 429 rate limit. Business-rule failures are explicit; never fall back to unrestricted access or automatic approval.
Retries
Mutation retries carry an idempotency key scoped to actor and action; a changed payload with the same key fails.
Retained from revision 1.3
Pipeline order (authenticate, membership, record, version, commit with event); indistinguishable denial (T27); expected-version stale-write conflict; idempotent repeats; rate limiting; no client-supplied company id trusted. Also kept from the 1.3 note because they do not conflict with GGA: secure session cookies, CSRF protection where applicable, input sanitisation and bounds, pagination, server-side secrets, database constraints and (if adopted) row policies as defence in depth (Blueprint p. 17).
Superseded
The 1.3 illustrative routes for questions, expressions, conversations, messages and actions (/v1/opportunities/{id}/questions, /expressions, /v1/conversations/...): no GGA feedback; Proposed carry-forward only. Build step: Step-03-Policy-Pipeline-and-Isolation-Harness.