Choosing a credential
Credentials
Organization key access
Read-only organization keys and organization-wide session inventory require a deployment containing the chat integration changes. See the package and deployment setup for availability. Choose an access tier when creating an organization key:
Create a read-only key with
createOrganizationApiKey(organizationId, { name, access: "read" }) from an authorized administrative backend. It cannot create sessions, send or control turns, change configuration, or mint other keys. Use a full-access key for the chat handler, which creates tenant workspaces and sends messages.
Both tiers can use listOrganizationSessions or iterateOrganizationSessions to discover readable sessions across the organization’s shared workspaces. Personal workspaces and Only me sessions are excluded. Agent access scopes and end-user filters do not restrict the organization key’s authority.
Authenticate users of your chat
createChatHandler uses your product’s resolve(request) hook on sends, history reads, and approval/question responses. Verify the product’s session cookie or bearer, then return the user’s allowed tenant and user ID. The organization key authenticates your backend to OpenGeni; it does not authenticate a product user to your backend.
The handler namespaces client conversation IDs to the resolved user. An opaque end-user label is not an OpenGeni account and does not grant authority. If you omit the user label, the host must resolve an authorized conversation itself.
For the React component, bind authKey to your signed-in user and tenant when using cookie authentication, change it on identity switches, and unmount on sign-out. This clears the old transcript and pending requests in the browser. The key stays local and does not replace server-side authentication. See Integrate your product.
Rules that hold everywhere
- Organization keys stay on the product server. List, create, and revoke them through the organization control plane; never embed one in a client.
- A delegated token cannot grant more than the host was configured to delegate, and it never receives a managed human’s personal-workspace authority.
- Every request is constrained by normal route authorization after authentication. A valid credential for one workspace does not reach another.
- Secrets an agent uses at runtime (provider tokens, MCP headers, variable sets) are encrypted at rest, are read only by explicit permissioned operations, and never appear in audit rows.
Deployment access modes
The full credential taxonomy, including stream tokens, enrollment tokens, sandbox bearers, and signed storage URLs, is in the repository’s credentials document.