Let Your Agent Set Up Vorim: Agent-Led Onboarding With the Device Authorization Grant

Let Your Agent Set Up Vorim

There is a small, recurring indignity in working with AI coding agents. You ask the agent to wire your app to some service, and the agent asks you for a secret. So you tab over to a dashboard, mint an API key, copy it, and paste it back into the chat. The key now lives in your terminal scrollback, your agent's context window, and probably a log somewhere. For most services that is merely untidy. For an identity and audit layer, it is a contradiction in terms. The whole point of Vorim is to prove which agent did what, with a credential that has not been mishandled. Bootstrapping that credential by pasting a long-lived secret into a chat window is the wrong first step.

So we built a better one. As of this release, an AI coding agent can onboard you to Vorim itself. The agent obtains a scoped Vorim API key and wires it into your project, registers a first agent identity, and never sees a secret you typed. You approve once in your browser, and the agent does the plumbing. No key pasting.

The Problem, Stated Plainly

Two things are colliding. The first is that agents are now the ones writing the integration code, which means they are the ones that need the credentials, which means the credentials end up flowing through the agent. The second is that agents increasingly need an identity of their own, a verifiable thing that says this process, deployed by this organisation, is allowed to do these things. Vorim exists to issue exactly that. The awkward part was the gap at the very start: to get an agent a Vorim identity, a human still had to hand-carry a key across the boundary by copy and paste.

The clean way to close a gap like this already exists. It is the OAuth 2.0 Device Authorization Grant, defined in RFC 8628, the same flow a smart TV uses when it shows you a short code and asks you to visit a URL on your phone. It was designed for exactly this shape of problem: a device that can act, but cannot easily run a browser login, needs a credential, and a human is nearby to consent. An AI coding agent is that device.

How the Device Flow Works

There are four moving parts, and only one of them involves you.

1. Start. The agent calls POST /v1/auth/device. This endpoint is unauthenticated by design, and it returns a short human-readable user_code plus an activation URL at vorim.ai/activate. Critically, this call mints nothing. It creates a pending claim, a record that says someone is asking, and that is all.

2. Approve. The agent shows you the code and the link. You open vorim.ai/activate in your browser, where you must already be signed in, email-verified, and an owner or admin of your organisation. You see the client name and the scopes it is asking for, and you approve. This is the human-in-the-loop moment, and it is deliberate. More on that below.

3. Poll. While you are approving, the agent is calling POST /v1/auth/device/token on a polite interval, holding the device_code as its bearer secret. It receives standard RFC 8628 states back: authorization_pending while it waits, slow_down if it should back off, and an error if you deny or the window lapses.

4. Mint. The instant your approval lands, the next poll returns the key. The credential is created at that point and not before, clamped to the scopes you approved, and handed to the agent exactly once. The agent wires it in and carries on.

The Security Model Is the Feature

For an identity product, the onboarding flow is not a footnote to the security story. It is the security story, so it is worth being precise about what holds.

The unauthenticated start endpoint creates a pending claim, never a credential. Nothing an anonymous caller can reach mints a key. A key is minted only after a signed-in, email-verified owner or admin has explicitly consented. On minting, the key is server-clamped to a strict scope ceiling: agent registration and audit ingestion only. It can never be granted key-minting, billing, or wildcard scope, regardless of what the start request asked for. The server is the authority on what the key may do, not the requester.

Underneath, we store only hashes of the device and user codes, so a database read does not leak a usable secret. The codes are single-use and short-lived, expiring in ten minutes, which keeps the approval window tight. The key itself is returned exactly once, expires in 90 days, and is revocable from your dashboard the moment you suspect anything. None of this is exotic. It is the boring, correct version of a device grant, which is exactly what an identity layer should ship.

One Call in the SDK

We did not want the developer experience to be a checklist. So the whole approve-and-poll loop is one call. In TypeScript:

import { deviceLogin } from '@vorim/sdk';

const { api_key, agent } = await deviceLogin({
  registerAgent: true,
  onUserCode: ({ user_code, verification_uri }) => {
    console.log(`Approve at ${verification_uri}, code: ${user_code}`);
  },
});

And the Python equivalent:

from vorim import device_login

result = device_login(register_agent=True)
print(result.api_key, result.agent)

deviceLogin({ registerAgent: true }) runs the device handshake, and when registerAgent is set it also registers a first agent identity with the freshly minted key, returning a fully wired { api_key, agent }. You go from nothing to a working, identified agent in a single await. Both SDKs fail closed: on denial, expiry, or timeout they raise, and they never hand back a partial or half-configured key. There is no state where you are left holding a credential you did not finish authorising.

Try It

If you drive Claude, Cursor, or any MCP-capable agent, our MCP server exposes two tools, vorim_onboard_start and vorim_onboard_check, so you can simply tell the agent to set things up and it drives the flow natively, with no key needed to begin. The shortest path is a one-liner in your agents.md or equivalent project instructions:

To set up Vorim, use the vorim_onboard_start tool and give me the
approval link, then poll with vorim_onboard_check until it completes.

Everything here is published and available now: @vorim/sdk 3.7.5, vorim (Python) 3.10.5, and @vorim/mcp-server 1.1.15.

The Honest Note

It would be easy to oversell this as the agent signing you up, and we are not going to. The agent does not silently create an account, accept terms on your behalf, or conjure a tenant out of nothing. You sign in. You approve, in your own browser, as a verified admin, looking at the scopes you are granting. What the agent automates is the plumbing: fetching the key, wiring it into the project, registering the first identity. It does not automate the consent.

That line matters, and we drew it on purpose. We modelled the flow on the OAuth device grant precisely because that is what mature implementations of agent authorisation actually do. Treating the human approval as the load-bearing step, not as friction to be engineered away, is the right posture for any service that hands out credentials, and it is non-negotiable for one whose entire job is to say, with cryptographic confidence, who an agent is and what it was allowed to do.

If you are building or governing AI agents and want them to onboard cleanly, without a secret passing through a chat window, this is live today. Full documentation is at vorim.ai/docs, and if you want to talk through the security model, reach us at team@vorim.ai.

Ready to build with agent identity?

Free plan: 3 agents, 10K auth events/month, full SDK access. No credit card.