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, either when an agent asks for it in a Session or under Settings → Integrations → Your integrations; from then on it is an integration of yours that every Session and coding task you own can use. The agent works with an opaque reference or a substitute token, and Roomote’s API adds the real key on the way out. These are personal API keys for HTTPS services, not a replacement for connected integrations.
Integration keys are gated per user. Turn on integration keys under Settings → Experimental to enable them for the Sessions you own.

​
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). It replies with a secure link into the Session. The approval waits 24 hours for the key.
  3. You open the link and enter the key. 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.
  4. The Session resumes on its own. The key is now an integration of yours: every Session you own, and every coding task launched from one, can use it within its policy until you revoke it.
You can also add an integration directly under Settings → Integrations → Your integrations, naming the origin, header, methods, and key yourself. Either way the result is the same kind of integration, listed and revocable there. 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 the Session itself, the agent can make single GET or HEAD requests to the approved origin. Roomote’s API sends the request with the real key and returns the response. This works everywhere and needs no setup. 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, the integration expires or is revoked, or you turn integration key tools off. 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.
  • Integrations are personal. Collaborators on a shared task never receive them, and a task only receives its acting user’s integrations.
  • 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.