Skip to main content

Store and rotate keys

  • Keep the organization API key in your secret manager, on the server only. Never put it in a browser bundle, a prompt, or modelContext.
  • Use a workspace API key for a component that needs only one workspace, and a read-only organization key for reporting.
  • Rotate by creating a new key, deploying it, and deleting the old one with deleteOrganizationApiKey. Keys can also expire.
  • Narrow a key’s permissions or workspaces with updateOrganizationApiKey. It takes effect on the next request.
See Authentication.

Receive events and supply credentials

To hear when work finishes, or to give each run short-lived credentials from your backend, register one webhook and one credential provider for all workspaces. See Webhooks and credentials.

Understand costs

API and embedded-product usage spends prepaid credits, not monthly plan credit. Connected AI subscriptions cannot serve API requests, even on a paid plan. Choose a credit-billed model, or connect your own provider API key; own-key fees follow the deployment’s configuration and are currently paused at 0% on app.opengeni.ai. Your provider still bills its own key usage. In the Opengeni apps, Free provides eligible accounts $10 monthly trial credit. Pro starts at $20/month; Pro, Max and Enterprise include connected AI subscriptions with no usage fee, within the provider’s limits. When credits run out on a credit-billed model, add credits before continuing.
  • One turn can include several model calls and tool calls. Long goals and large tool schemas cost more.
  • getBillingUsage returns usage for accounting (requires billing permission).
Organization owners and admins receive alerts when general available credits reach $10 or run out, and when hourly spending is unusually high. Scoped promotional and Free-plan funding is separate and may remain usable. Read the threshold with getBillingAlertSettings({ accountId }) and change it with updateBillingAlertSettings({ accountId, lowBalanceThresholdMicros }) (USD micro-units; requires billing-management permission). listBillingCreditNotifications returns the current recipient’s retained notices. The backend contract describes the spend rule, receipt semantics and top-up integration.

Keep SDK and server compatible

Server updates don’t break existing integrations: the API only grows, so a pinned SDK keeps working and you upgrade when you want new features. Rare exceptions (an emergency security fix or an explicit product-owner decision) are announced with migration notes. Pin all @opengeni packages to the same version, install stable releases (the npm latest tag) rather than canaries, and let your code ignore unknown response fields and event types. Deprecated members keep working; their docs name the replacement. Read the server version from /healthz. See the API compatibility policy. Our published SDK test matrix exercises pinned stable releases and known integrator pins against the current server. The bounded test matrix is not a limit on the compatibility promise.

Keep the tool surface minimal

Every visible tool costs prompt tokens and widens what the agent can do. For an agent that should use only your tools, return this from the proxy’s createSession hook:
capabilities: "none" limits the agent to the session’s own tools plus the essentials: no Opengeni workspace or session tools, workspace connectors, or bundled Opengeni guides, so empty firstPartyMcpTools or bundledSkillIds lists add nothing. See Configure the agent. Organization owners can restrict which integrations may be set up in Organization settings → Integrations.

Test isolation before launch

Verify that:
  • user A cannot open, stream, message, or attach files to user B’s session through your routes;
  • a request carrying another workspace or session id is rejected;
  • your tools refuse another tenant’s records even when the model asks for them;
  • concurrent onboarding for the same tenant converges on one workspace.

Clean up

A workspace can’t be deleted while a session is running. Owners can set a retention policy in organization settings.
Using a coding agent? The opengeni-client skill covers this.