API keys and signing in from an agent
How an agent signs in, and the key for one that cannot open a browser.
An agent reaches your Roma account in one of two ways. Most sign in: a browser opens Roma's sign-in, you approve the agent, and it keeps that sign-in from then on. An agent that cannot open a browser uses an API key instead, which you create under Settings, then Connections. Either way the agent acts as you, on your own lists, and reaches nothing else. Agents in Roma explains what a connected agent is.
Signing in from an agent
When you add Roma to an agent, the agent calls Roma's address and learns it has to sign in. A browser opens Roma's sign-in, where you use the same Google or Apple account as always. Then a screen asks you to approve the agent. It names the app and says where it returns you after approval, claude.ai, chatgpt.com, or an app on this computer, so a look-alike cannot pretend to be a real app. Only approve a request you started in that app yourself.
Nothing is pasted and no key is copied. The agent receives a sign-in of its own that lasts an hour at a time and renews itself, so you are not asked again. An agent that keeps nothing between conversations, one that lives in your messages, signs in again when it needs to, or takes a key.
An app that returns to a web address gets the browser straight back. An agent on a cloud computer of its own leaves the browser on Roma's connected page, which shows a link to copy and paste back to the agent. That link, like the sign-in link itself, is good for ten minutes.
When an agent needs an API key
A key is for the agent that has no browser to open and nowhere to keep a sign-in: a scheduled job, a self-hosted agent, a client that only takes a pasted key, or the loop on your Mac that polls a trigger for events (Triggers: wake your agent when something changes). Claude Code, Codex, Cursor, VS Code, Gemini CLI, Poke, OpenClaw and Hermes Agent each have a place for one. ChatGPT and Claude on the web do not take a key and sign in instead.
A key does not expire, and it acts as the whole you on your own workspace, exactly like a sign-in. An agent that can do both should sign in: you approve it in your own browser, the sign-in is short-lived, and nothing has to be pasted.
Create a key
Open Settings, then Connections, and scroll to API keys at the bottom, under Connect your AI to Roma.
Press Create key.
Copy the key now. It is shown only this once: Roma keeps a fingerprint of it, never the key itself, so a key you lose cannot be shown again. Create a new one instead.
Paste it where the agent asks for a bearer token. Where an agent asks for a header rather than a key field, the header is
Authorization: Bearerfollowed by the key.
A key starts with roma_. Once created, the row shows the key's first characters, the day it was created and when it was last used, or Never used until an agent has called with it. You create a key in Roma in the browser or in the Mac app. The account is the same everywhere, so the key works for any agent.
One key at a time
Settings holds one key. Create new key replaces the key you have, and the old one stops working on its next call. That is also the way to rotate a key you think may have leaked. Revoke stops the key without creating another. An agent whose key was replaced or revoked gets a refusal on its next call and needs the new key.
Keep it like a password
A key acts as you. Keep it out of prompts, shared configs and anything you publish, share it only with an agent you trust, and revoke it in the same place when the agent no longer needs it. The Settings page says it in one line: for an agent that cannot sign in, treat a key like a password.
Disconnecting an agent that signed in
Remove Roma in the agent's own settings. That deletes the sign-in the agent holds. Signing out of Roma in the browser does not disconnect an agent, and disconnecting an agent does not sign you out of Roma. To have the grant revoked on Roma's side as well, write to hello@roma.app.
Whichever way an agent got in, everything it changes shows in your Event Log as your own action, marked as coming through that agent: The Event Log and reverting a change. What an agent can and cannot do in your account lists what the sign-in or the key reaches.
Questions people ask
Does a key let an agent do more than signing in would?
No. A key and a sign-in reach exactly the same things: your own lists and the items on them, what others shared with you, your automations, the trash, and a read-only view of what Roma remembers about you. Neither reaches your connected apps or your email.
Can I have a key for each agent?
Settings holds one key at a time, and creating a new one replaces it. Give the same key to every agent that needs one, or sign the others in, which most agents can do. Revoking the key signs out every agent that used it.
My agent says its key was refused. Why?
The key was replaced by a newer one or revoked, both under Settings, then Connections. Create a key there and give the agent the new one. A key that was never created there, or copied with a character missing, is refused the same way.
Is the key sent anywhere else?
No. The agent sends it to Roma's address with every call, and Roma checks it against the fingerprint it kept. Roma never shows the key again and never sends it to anyone.