Skip to main content

​
People in a workspace

Today a workspace has one person: its owner, whose first sign-in created it. There are no member invites yet, so nobody else can be added to a workspace, and someone else who signs up gets a workspace of their own. Settings → Plan & billing → Your access shows your role. Hookie’s other roles already matter, because the two credentials that act for a person are held to them. An API key carries a role, and a connected agent is clipped to one by the access you grant it.

​
Roles

Each role can do everything the role below it can: A member role, from before these four existed, reads as viewer. Single sign-on through your own identity provider (SAML or OIDC) is planned and not available yet, on any plan: Settings → Single sign-on says Coming soon. People sign in with an emailed code or with GitHub.

​
API keys

An API key (hk_…) lets a system with no browser, such as a CI job, a script or your own backend, call the admin API and the hosted MCP server at /mcp. Owners and admins create them in Settings → API keys, and only a person signed in to the console can: an agent or another key cannot.
  • A key acts as the person who created it, and its role, viewer, developer or admin, is a ceiling on that person’s role. There is no owner role for a key, so billing is out of its reach.
  • A key can be limited to one project, to an expiry date, and to an IP allowlist.
  • A key is shown once. Hookie keeps only its SHA-256 hash. Revoking a key stops its next request.
API keys covers creating, using and revoking them.

​
Connected agents

A connected agent is a coding agent, such as Claude Code, Cursor or any MCP client, that you connect to https://app.hookie.ai/mcp over OAuth. It signs in as you, through WorkOS AuthKit, and then holds a token it refreshes on its own: there is no key to paste anywhere. The Connect agent button in the console’s top bar opens Connect an agent, with the URL and the setup steps. What it may do is decided separately, by you, in Settings → Connected agents. A newly connected agent can only read. Change access gives it one of three levels, each including the one before: An agent’s authority is your own role narrowed to the level you granted, whichever is lower. A change applies on its next request, with no need to reconnect. Revoke cuts it off on its next request too, even though its token is still valid, because Hookie checks the grant on every call. At every level, an agent cannot touch billing, manage connected agents, create API keys, or reveal or rotate a destination’s signing secret. Everything it does is written to the audit log with you as the actor and the agent’s client id beside it. Connected agents lists every tool and what each level unlocks.

​
The same ladder

API keys and agents share one ladder, so the same words mean the same thing everywhere: A call above what a credential holds is refused with 403. For an agent, the answer names the scope the call needs and links to Settings → Connected agents, so you can widen it.

​
Other credentials

Three more credentials exist, and none of them acts for a person or reaches the admin API:
  • An ingest key (ik_live_…) sends events into one project, and tails its live stream. See Endpoints and ingest keys.
  • A Data API key (hdk_…) reads the datasets and columns one project exposes. See Data API.
  • A portal token lets one of your customers into your customer portal.