Skip to main content
Integration keys let a Roomote agent use an API key you hold, for one HTTPS service, without the key ever entering chat, a prompt, a task environment, or a transcript. You enter the key once when an agent asks for it in a session, under Personal Settings → Personal integrations, or, for administrators, on the Integrations page. Personal integrations are available only to their owner; deployment-wide integrations are available to active members. The agent works with an opaque reference or a substitute token, and Roomote’s API adds the real key on the way out. Integration keys are for HTTPS services, not a replacement for connected integrations. When you ask Roomote to connect a service without saying how, it first checks the read-only built-in catalog, including providers that are off or not yet authorized. A matching built-in uses its native OAuth, its secure form on the Integrations page, or its keyless path. If the provider is not built in, Roomote checks for the service’s official remote MCP server and what connecting requires. If the provider must approve or allowlist clients, or access is limited to a beta or plan, Roomote uses an integration key and mentions the MCP as an option. Otherwise it uses an integration key only when no supported MCP applies. An explicit request for the service’s API goes directly to the integration-key route. A permission denial or pending or denied authorization is never bypassed with another route.

​
How an approval works

  1. You ask for something that needs a service you hold a key for, such as “list my Stripe customers”, or share a link into a service Roomote has no connector for but whose API accepts a key you hold, such as a Figma frame or an Intercom conversation.
  2. The agent reads the service’s documentation and prepares an approval with only nonsecret policy: a label, the exact HTTPS origin (for example https://api.stripe.com), the header that carries the key, and the HTTP methods the work needs (read-only by default). The approval waits 24 hours for the key.
  3. While you are viewing the session, the key form opens automatically. If you dismiss it, a service-specific card such as Add your Figma key remains at the end of the conversation, and the agent’s secure link opens the same form. Enter the key there; the form bypasses chat and is excluded from capture and replay. If the agent asked for write methods, the form shows them and you confirm them. Choose Only me for a personal integration or Everyone in this deployment for a shared integration.
  4. The session resumes on its own. Personal integrations are available to your sessions and coding tasks. Deployment-wide integrations are available to active members while the integration owner remains active.
If a built-in integration or remote MCP server is still waiting for authorization, Roomote shares that link again rather than opening a key approval. You can also add a personal integration directly under Personal Settings → Personal integrations, naming the origin, header, methods, and key yourself. Administrators add deployment-wide integrations on the Integrations page. Owners and administrators can change a shared integration to personal access; Roomote then moves it to the owner’s Personal Settings. An integration covers one origin. Nothing the agent sends can change the origin or widen the methods. Integrations are kept until you revoke them; you or the agent can set a lifetime in hours instead when a key should be temporary.

​
What agents can do with it

In a human session turn, Roomote can discover existing integration keys, prepare secure approval requests, and make one or a few direct calls to an approved origin using any HTTP method approved for that integration. Roomote’s API sends the request with the real key and returns the response. For scripts, SDKs, CLIs, or many calls, Roomote launches an attached coding task instead. In coding tasks launched from the session, the task receives each approved service as a substitute token in its environment, plus one base URL. The agent calls the service through that base URL with the substitute as its bearer token, using curl, a script, an SDK, or a CLI, with any of the approved methods. Roomote’s API forwards the request to the real origin and places the real key in the header the service expects. The substitute only works through that proxy, only from that task, and only while the approval and the task are live. The real key never enters the sandbox. Coding tasks pick up approvals when they start or resume. A key approved while a task is already running becomes available to the next task.

​
Header names

An approval names the header that carries the key at the approved origin: authorization, optionally with a Bearer, Basic, or Token scheme, x-api-key, api-key, or the service’s own header such as private-token or x-shopify-access-token. A scheme is only accepted on authorization. Headers that shape the request itself, such as cookies, host, content framing, and proxy or forwarding headers, cannot carry a key. Inside a coding task the agent always sends the substitute as a bearer token; the proxy moves the real key to the right header.

​
Security boundary

The approved origin receives the key. It can use whatever privileges the key grants, including write privileges even when the approval is read-only, and some services perform side effects on GET. Approve a least-privilege, disposable key and only a service you trust. Responses are visible to the agent and may enter the transcript, and a service can disclose partial or transformed values that Roomote cannot recognize. This is not a data-loss prevention guarantee. Substitutes are capabilities. A substitute token is bound to one task, one integration, and the task’s current generation, and it stops working when the task ends, or the integration expires or is revoked. Within that window, a copy of the substitute could be used from elsewhere against the same origin. Roomote never logs substitutes or keys, strips them from snapshots, and refuses responses that echo the key. Do not put keys in labels, origins, paths, task prompts, task environment files, or ordinary session messages.

​
Limits

  • One origin per integration; paths under it are not restricted beyond the approved methods.
  • Personal integrations are available only to their owner. Deployment-wide integrations are available to active members, stop working when their owner becomes inactive or is deleted, and remain manageable by administrators.
  • A task receives only the integrations available to its acting user.
  • Services that sign requests with the secret (for example AWS Signature V4) cannot be used, since the key must be present where the signature is made.
  • Streaming responses, WebSockets, and redirects are not relayed through the proxy; responses are capped at 8 MiB.
  • SDKs that allow a host override but no path prefix need a dedicated proxy hostname; see below.

​
Self-hosting

No configuration is required. Optionally set R_CREDENTIAL_EGRESS_PROXY_HOST on the API and controller to a hostname pointed at the API service, so coding tasks receive https://<that host> as their base URL and host-only SDK clients work. See environment variables.