Partner API :: Geena API

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started From nothing to a working “Connect with Geena” button, in order. Everything here happens once, at setup time; the demo apps are a complete worked example of the result. 1. Create your organization Sign in at dashboard.test.geena.eu (email + one-time code — the account is created on first login) and create your organization. The organization is the owner of everything that follows: manifests, app credentials, and the connections users grant.

Connect with Geena

Mon, 01 Jan 0001 00:00:00 +0000

Connect with Geena One button in your app opens a popup on Geena’s origin; the user logs in (email + one-time code — first-time users are provisioned on the spot), sees one consent screen with your manifest’s asks and terms, and the popup closes. Your backend then exchanges a short-lived code for tokens and the connection’s request_id. Returning users with a live consent skip the screen entirely — the popup flashes and closes.

Connections & status

Mon, 01 Jan 0001 00:00:00 +0000

Connections & status List your connections GET /partner/v1/requests Authorization: Bearer Returns every active connection your organization holds with the token’s user — the recovery path when you did not store request_id at connect time. Pending invitations are never listed: before consent there is no connection.

Reading & writing data

Mon, 01 Jan 0001 00:00:00 +0000

Reading & writing data Slot kinds map to three record types: schema slots serve structured documents, id_document slots serve identification documents, personal_files slots serve files. Reading a granted item needs no verb — that is what a connection is; writing and deleting need the slot’s edit verb (visible in /status). Every operation below also requires a grant; a slot the user has not granted answers 404 not_found, indistinguishable from one that does not exist.

Filling slots in-app

Mon, 01 Jan 0001 00:00:00 +0000

Filling slots in-app A pending slot does not have to send the user to Geena: with the user present in your app you can render a native picker over what their vault already holds, let their tap grant an existing item, or create the asked-for value directly into their vault — granted to the slot in the same act.

Relatives & subjects

Mon, 01 Jan 0001 00:00:00 +0000

Relatives & subjects A manifest can ask about people beyond the account holder: each child you cover, your co-driver. Those asks are subjects — declared once in the manifest with a relation (child, partner, …) — and every slot that carries a subject id in /status asks about that role rather than about the user. The user answers a subject with their family-member vaults: vaults they own and hold data in on a relative’s behalf. Your app never sees those vaults' ids — every person is addressed by a pairwise alias, minted per connection, meaningless to any other organization.

Errors & step-up

Mon, 01 Jan 0001 00:00:00 +0000

Errors & step-up The error envelope Plane errors are JSON with a stable machine-readable code: { "error": "not_found", "message": "no such item" } HTTP error Meaning 400 invalid_body Missing/malformed body (e.g. no data object, no file part) 400 invalid_document Payload fails the schema it is validated against 400 unsupported_item Operation not defined for the slot’s kind (e.g. create on id_document) 401 unauthenticated No valid caller behind the token 403 partner_token_required A first-party (non-partner) token was presented 403 unknown_client The token’s client is no longer registered 403 organization_suspended Your owning organization is suspended 403 connection_inactive The connection is revoked, withdrawn, or expired 403 verb_not_granted The slot does not carry the verb this operation needs 403 delete_refused The platform protects this document from deletion 404 not_found Ungranted, foreign, malformed, or nonexistent — deliberately one answer 409 ambiguous_item The (kind, target) pair matches several slots / records — use slot ids 423 sealed The user’s vault is sealed; see step-up below 500 server_error Transient server failure — safe to retry Info Read 404 as “nothing for you here”, never as “does not exist.” The same answer covers an item the user declined to share, an id from another user, and an id that was never real. Probing teaches nothing — by design.

Recipes

Mon, 01 Jan 0001 00:00:00 +0000

Recipes Copy-paste sequences for the common jobs. Everything below assumes an active connection and a bearer token: API=https://api.test.geena.eu/partner/v1 REQ= # from the token exchange, or GET $API/requests AUTH='Authorization: Bearer ' All of these flows are implemented end-to-end in the public demo apps — github.com/Identa-io/demo is the reference integration. Read everything the user granted curl -H "$AUTH" $API/requests/$REQ/status # for each item with status=granted: curl -H "$AUTH" $API/requests/$REQ/slots/ Serve-on-read means you always get the current version — if the user updates their address in Geena, your next read has it. Do not cache what you were not granted keep for.

OpenAPI specification

Mon, 01 Jan 0001 00:00:00 +0000

OpenAPI specification The /partner/v1 plane is defined by an OpenAPI 3.0 document — the same file the Geena backend generates its routing from, so the published contract cannot drift from the implementation. Download partner-v1.yaml curl -sO https://docs.test.geena.eu/openapi/partner-v1.yaml Use it to generate a typed client in your stack (openapi-generator, oapi-codegen, openapi-typescript, …) or to import the collection into an API tool. Two conventions worth knowing when reading it: