Partner API

Partner API

Everything your app needs to hold a connection with a Geena user: a “Connect with Geena” popup that logs the user in and captures consent in one screen, then a small REST plane (/partner/v1) for reading, filling, and maintaining the data the user granted you.

The model in six sentences

1. Your organization publishes a manifest in the Geena dashboard — the versioned shape of what you ask for: slots (a passport, a proof-of-address document, supporting files, …), presentation groups, and terms.
2. When a user consents, Geena mints a connection (internally: an accepted request) pinning that manifest version. The connection id — request_id — is the address of everything else in this API.
3. Data rights come from per-slot grants the user controls, never from OAuth scopes: your tokens carry identity only, and every call re-checks the grant behind it.
4. Every act on the plane — reading a value, listing candidates, attaching, creating, writing, deleting — is receipted to the user’s timeline with your app’s client id. Design your integration expecting the user to see it.
5. A manifest can also ask about people beyond the account holder — subjects (“each child you cover”): the user answers those in your app from their family-member vaults, addressed only by pairwise aliases.
6. What the user did not grant is invisible: an ungranted, foreign, malformed or nonexistent id all answer the same 404 not_found, and a pending slot is indistinguishable from “the user has no such data” (the oracle rule).

Section contents

• Getting started — organization, app registration, manifest authoring and publishing, wiring the ids into your app.
• Connect with Geena — the popup ceremony, PKCE, the code exchange, token lifecycle.
• Connections & status — discovering your connections and driving your UI from per-slot status.
• Reading & writing data — serving granted slots, file content, delegated writes and deletes.
• Filling slots in-app — the native picker: candidates, attach, slot-bound create.
• Relatives & subjects — manifests about the family: person candidates, adding a child, filling per person.
• Recipes — copy-paste sequences for the common jobs: fill, update, relatives, files, login, revocation.
• Errors & step-up — the error envelope, code table, sealed vaults and the hosted verification hand-off.
• OpenAPI specification — the machine-readable contract for /partner/v1.

Base URLs (test environment)

All /partner/v1 calls take Authorization: Bearer <access token>.