Workstate Docs

Keys & attribution ​

An API key lets an agent act as you. Each key belongs to one person, never to a team, so everything an agent writes with your key is attributed to you. Attribution is the record of who wrote a ledger entry, and with which agent.

People sign in to the console with GitHub, and a console session lasts 7 days. Agents do not sign in: they use keys.

Your keys ​

  • You create keys on the API keys page, under Create a key. Only a person signed in to the console can create a key. A key cannot create another key, so a leaked key cannot outlive its revocation.
  • A key starts with rgc_live_, then a short prefix that identifies it, then a long secret. The console lists your keys by their prefix.
  • Workstate shows a key once, when you create it. It stores only the prefix and a SHA-256 hash of the key, so it cannot show the key again. If you lose a key, revoke it and create another.
  • You can hold up to 25 live keys. Make one for each machine or agent, so you can revoke one without breaking the others.
  • Keys do not expire, and they have no scopes. A key reaches every namespace its owner can reach, and loses a namespace as soon as its owner does.
  • The API keys page lists your keys with their label, their status, when they were created, and when they were last used.

How agents use a key ​

An agent sends the key with every request, in the header Authorization: Bearer <key>. The configuration on the API keys page reads the key from the RAG_API_KEY environment variable, so the configuration file holds no secret.

A request with a missing, empty, unknown or revoked key fails with 401.

What attribution records ​

Every ledger topic, and every entry in its history, records three things:

  • The author: the email address of the person who owns the key. An agent cannot choose it. Workstate takes it from the key, and ignores any email address the request sends.
  • The agent label: a name for the agent, such as the client or model the person used. It comes from the tool call's agent argument or from the X-RAG-Agent header. The label is self-reported: Workstate records it but cannot verify it.
  • The time.

The console shows the author and the agent label on each topic ("Opened by …") and on each history entry.

Because the author comes from the key, a ledger entry shows whose key wrote it, not a name that anyone could type. That is why Workstate gives every person their own keys, rather than one key for the whole team.

Revoking keys ​

  • Revoke one of your own keys on the API keys page. It stops working on its next request.
  • Owners and admins can revoke all of a person's keys at once on the Team page, for example when someone leaves. Only an owner can revoke an owner's keys.

Revoking keys does not remove the person's seat, and it does not stop them signing in to the console. Permissions explains what this means when someone leaves.

Limits ​

  • Keys do not expire, and you cannot limit a key to one namespace or to reading only. Treat a key like a password.
  • The agent label is self-reported, so it shows what the agent said it was.
  • Connecting an agent by signing in, without pasting a key (MCP OAuth), is not built yet Coming soon.
  • Usage limits and usage reports for each person are not built yet Coming soon.

Workstate is built by Nerdstorm Pty Ltd, Sydney.