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.

2. Register your app

Your OAuth client is registered by the Geena team: email support@geena.eu with your organization name, a display name for the consent screen, a privacy-policy URL, and your exact redirect origins (scheme + host + port, e.g. https://app.example.com — the redirect_uri must match one of them origin-exactly).

You receive a client_id and a client_secret (shown once — store it in your backend’s secret store; it never belongs in browser code). Registration also sets your organization’s capability: which schema targets and verbs (fill/edit/keep) your manifests may ask for. Ask for what you plan to use — a manifest a user cannot accept helps nobody.

3. Author and publish a manifest

In the dashboard, Manifests → New. A manifest is the versioned shape of your ask:

Slots — each one thing you ask for: a built-in schema (PersonFullName, PersonAddress, …), an identification document, or supporting files, with the verbs you need beyond reading (fill to collect in-app, edit to push updates, keep to hold a revocation-surviving copy).
Groups — presentation sections, mirrored back to you in /status.
Subjects — declare them if you ask about family members (“each child you cover”) — see Relatives & subjects.
Terms — legal basis, purpose, retention; rendered verbatim on the consent screen.
Initiation — who may start a connection: your organization, the recipient (the button lane), or both.

Publish the manifest and copy its manifest id from the card. Editing later creates a new version — existing connections stay pinned to the version the user accepted; re-consent is what widens them.

The manifest card also offers Export JSON (and the list page Import JSON) — author once, move the same shape between environments, keep it in your repo. The demo manifests are importable examples.

4. Configure your app

Three values, all deployment configuration:

GEENA_API_URL   = https://api.test.geena.eu
CLIENT_ID       = <from registration>        # public
CLIENT_SECRET   = <from registration>        # backend only
MANIFEST_ID     = <from the published card>  # public — it travels in the authorize URL

Different products with different asks are simply different manifest ids on different buttons.

5. Add the button

Implement the connect ceremony: popup to /oauth/authorize with PKCE and your manifest_id, a landing page on your registered origin, a server-side code exchange. The exchange hands you tokens and the request_id — store it; it is the address of everything else.

6. Verify the loop

curl -H "Authorization: Bearer <access token>" \
  https://api.test.geena.eu/partner/v1/requests/<request_id>/status

You should see your manifest’s groups and slots with their grant status. From here: read what was granted, fill what is pending in-app, and keep the recipes open — they cover the common jobs end-to-end.