Skip to main content
Sessions belong to workspaces; organization routes manage shared workspaces, keys, and sessions across them. Which credential you use depends on who is calling.

​
Choosing a credential

​
Credentials

​
Personal sign-in methods

In managed mode, Google, GitHub, and email/password can all sign in the same user. When a social provider presents an email that matches an existing user, Opengeni links it automatically if both emails are verified. Linking keeps the user’s workspaces, history, memberships, and billing. Unverified or different emails are not linked. Manage sign-in methods in Personal settings → Security. Sensitive changes require a recent sign-in, and you must keep at least one method. After you disconnect a provider, reconnect it from the same page. Sign-in methods are not integration permissions. Google sign-in does not grant Gmail or Drive access, and GitHub sign-in does not grant repository access. Connect those separately.

​
Organization key access

An organization key’s policy sets both its permissions and its workspace scope:
The preset is a label. The server grants only the permissions you send and recomputes the label from them. Each permission, including workspace:admin, is granted individually. To give a backend plaintext secret values, add secrets:read to a custom list. The old variable-sets:* names still work as aliases of the matching secrets:* permissions. Scope { kind: "all" } covers every current and future shared workspace in the organization. { kind: "selected", workspaceIds } takes up to 500 shared workspace IDs from the same organization. Personal workspaces are never in scope. Older integrations can keep using the legacy access selector: Omitting both policy and access creates a full legacy key. Don’t combine policy with legacy selectors. Integrations that provision tenant workspaces, onboard members, and create sessions as users need all-workspace scope and full permissions. Keys with sessions:read can call listOrganizationSessions or iterateOrganizationSessions across their shared workspaces. Personal workspaces and Only me sessions are excluded.

​
Inspect and edit a key

getOrganizationApiKey(organizationId, apiKeyId) returns the key’s metadata and policy. updateOrganizationApiKey(organizationId, apiKeyId, { name?, description?, policy? }) changes at least one field; description: null clears the description. Both return an ApiKey without the token. Only creation returns { apiKey, token }. A policy edit replaces the whole policy and takes effect on the next request, without rotating the token. Supplying a policy moves a legacy key to explicit permissions. Check apiKey.permissionMode (legacy or explicit), apiKey.policy, and apiKey.workspaceScope.

​
Inspect what a key can do

getAccessContext() / GET /v1/access/me returns a credential object for requests made directly with an organization or workspace API key. It contains:
  • kind: organization_api_key or workspace_api_key
  • access: full, read, or developer_setup (organization keys only)
  • accountId and workspaceId (null for organization keys)
  • effectiveWorkspacePermissions
  • policy and workspaceScope (organization keys)
An organization key’s workspaceGrants may be empty even when it can reach shared workspaces. Use listWorkspaces() to list the workspaces it can reach. credential is absent for asUser requests, signed-in users, and delegated tokens.

​
Authenticate users of your chat

createSessionProxyHandler and createChatHandler call your resolve(request) hook on every request. Verify your product’s session cookie or bearer there, and return the user’s tenant and user ID. The organization key authenticates your backend to Opengeni; your backend authenticates your users. A conversation ID is not scoped to a user. Your backend decides which conversations a user may open. An end-user label does not grant workspace membership. On sign-out or a user or tenant change, abort pending requests, clear transcripts in your frontend, and remount session components. See Users, tenants & privacy.

​
External users

When the organization key acts as one of your users (through the session proxy, the chat facade, or asUser), Opengeni adds that user to the workspace on their first request. They get conversation permissions: workspace read, session create/read/control, file upload/read, and mcp_servers:attach. The key must hold members:manage and those permissions; a full-access key does. Existing memberships are never changed. To choose permissions yourself, call addExternalWorkspaceMember before the user’s first request, and updateExternalWorkspaceMember to change them later.

​
Rules that hold everywhere

  • Keep organization keys on your server. Never embed one in a client.
  • A delegated token cannot grant more than the host is configured to delegate, and it never reaches a user’s Personal workspace.
  • A credential for one workspace does not reach another.
  • Secrets agents use at runtime (provider tokens, MCP headers, vault items) are encrypted at rest, readable only with explicit permissions, and never written to audit rows. Agents use vault items by {{secret:…}} reference, so the values never enter the model context.

​
Deployment access modes

Every other credential, including stream tokens, enrollment tokens, sandbox bearers, and signed storage URLs, is listed in the repository’s credentials document.