Organization API
Organization API
The Partner API is the user’s side of a
connection: a token bound to one person reads and fills what that person
granted. The Organization API (/org/v1) is your organization’s side:
what it already holds — the requests people accepted, the copies it kept, the
files it holds for a request, and the update proposals addressed to it —
reachable from your own systems with a member-bound token instead of a
dashboard session. It is the plane a back office, a CRM sync or a KYC workflow
speaks; the dashboard’s organization pages run on exactly the same rules.
The model in five sentences
- A request is one manifest version sent to one person; once accepted it
is the connection the partner plane addresses as
request_id. Your organization sees every request it holds, pending invitations included. - Per slot, a request lists records — one per standing grant, each naming
its
participant(nullfor the recipient themselves) and the version the person’s source stands at right now. Records describe answers already given; a party who never shared anything never appears. - Under a
keepverb your organization holds a kept copy in its own vault — taken manually, or automatically under the slot’s adoption policy. Every copy of one record under one request and slot is a version of one org document, and your own corrections append to that chain without ever touching the person’s data. - Request files are the files you hold for a request: the copies you kept of the person’s files, and files you attached yourself. The person sees neither.
- When a source you keep a copy of gets a newer version, an update proposal reaches the request: you keep the new version or dismiss the notice.
Getting a token
Switch Organization access on for the app first (Organization → Apps in
the dashboard — an organization admin does this; a client the Geena team
registered gets it on request). Then a member of your organization signs in
through the connect ceremony with
scope=profile offline_access organization and no manifest_id — see
Organization access
for the screen and the “if member” narrowing. What comes back is an ordinary
partner access token whose consent carries organization; refresh and revoke
it like any other. Check the token response’s scope before using it here:
without organization the person is not a member, and this plane refuses the
token with the security gate’s 403 envelope (a missing scope), just as it
refuses first-party dashboard tokens (403 partner_token_required).
Every call re-checks, live, that the person behind the token is still an
active member of the organization that owns your client (403 not_a_member
otherwise) and that their role covers the act (403 role_insufficient). The
plane serves only your organization’s own material; anything else — foreign,
malformed, nonexistent — is the same 404 not_found, the oracle rule.
Roles
| Act | Role floor |
|---|---|
| List requests; read one request in full | request_read |
| Read kept copies and their bytes; keep; retry pending keeps; correct; read and decide proposals | request_manage |
| Attach a file of your own to a request | request_manage + file_create |
| Replace or rename a file you attached | request_manage + file_update |
| Delete a file you attached | request_manage + file_delete |
Roles are what the dashboard gives your team under Members; the plane requires of a person exactly what the dashboard requires of the same person.
Keys
Reading a kept copy, a proposed version or a file’s bytes opens your
organization’s key in the member’s key context. When it cannot be opened
there — for example, a membership the member has not yet activated by signing
in to the dashboard — the call answers 423 org_sealed; retry once they have.
Errors
Same envelope as the partner plane — { "error": "<code>", "message": "…" }:
| HTTP | error |
Meaning |
|---|---|---|
| 400 | invalid_body |
The body is not the one the route takes (no file part, a non-integer expected version, no label) |
| 400 | invalid_document |
Corrected values do not satisfy the copy’s own schema |
| 400 | unsupported_item |
The act does not apply to the addressed item (e.g. downloading a document adoption) |
| 403 | partner_token_required |
A first-party (dashboard) token was presented; a partner token without the organization scope gets the gate’s {"errors":[…]} envelope instead |
| 403 | unknown_client |
The token’s client is no longer registered |
| 403 | organization_suspended |
Your organization is suspended |
| 403 | not_a_member |
The person behind the token is no longer an active member |
| 403 | role_insufficient |
The member’s role is below the act’s floor |
| 403 | adoption_refused |
This record cannot be kept, corrected or written: a copy still pending, a kept file on a write, a correction with nothing kept, an alias naming no record |
| 403 | participant_ineligible |
The recipient may no longer answer for that party, and the keep took nothing |
| 404 | not_found |
Foreign, malformed or nonexistent — deliberately one answer |
| 409 | version_conflict |
What you pinned a write to is no longer current — re-read and re-apply, never resend with fresh numbers |
| 413 | too_large |
The upload exceeds the per-file cap (32 MiB by default); nothing written |
| 423 | org_sealed |
Your organization’s key could not be opened in this member’s context (e.g. a membership not yet activated) — retry |
| 500 | server_error |
Transient server failure — safe to retry |
Section contents
- Requests, records & kept copies — listing and reading requests, who answered what, keeping copies, reading and correcting them.
- Request files — the files you hold for a request: kept copies and your own attachments, versions, bytes.
- Update proposals — newer versions of sources you keep: preview, keep, dismiss.
- OpenAPI specification — the machine-readable
contract for
/org/v1.
Base URL (test environment)
https://api.test.geena.eu/org/v1 — every route below is relative to it and
takes Authorization: Bearer <access token>.