Agent Onboarding

AI agents can sign users up for Swirls. A user tells their agent to set up Swirls, the agent registers with the Swirls auth server, the user approves once, and the agent receives a scoped credential it can use to create projects and deploy workflows. If the user is new to Swirls, their account and workspace are created during registration. No separate signup.

Swirls implements the auth.md standard for agent registration. The machine-readable contract lives at swirls.ai/auth.md.

If you are an agent reading this: fetch https://swirls.ai/auth.md and follow it. Everything below is background for humans.

Motivation

More users arrive at new tools through an agent than through a landing page. The agent reads the docs, writes the workflow, and is ready to deploy. Then everything stops so a human can complete a signup form, generate a credential, and paste it back into the conversation.

Agent onboarding removes that stop. The agent registers itself, the user approves with one click and one short code, and the work continues. The user gets a real account, a workspace, and a signed-in dashboard session out of the same approval.

Design

Registration is handled by the Swirls auth server at auth.swirls.ai. Agents discover it the same way OAuth clients do:

1. Any unauthenticated API request returns a 401 with a WWW-Authenticate header pointing at the protected resource metadata.
2. The resource metadata points at the authorization server metadata, which carries an agent_auth block describing the registration endpoints and supported flows.
3. swirls.ai/auth.md documents the same contract as plain Markdown, readable by agents and humans alike.

Two registration flows are supported.

Agent-verified

Agent platforms that can mint an ID-JAG identity assertion for Swirls register in a single request. The platform asserts the user's verified email, Swirls verifies the assertion against the platform's published keys, and the credential is issued immediately. Repeat registrations from the same platform identity always route to the same Swirls account.

This flow is active when the authorization server metadata lists urn:ietf:params:oauth:token-type:id-jag in identity_assertion_types_supported.

User-claimed

Any agent that knows the user's email address can register. Swirls emails the user a one-time approval link. The link signs the user in, creating their account and workspace if needed, and shows a consent page listing exactly what the agent will be able to do. Approving reveals a 6-digit code. The user reads the code to the agent, and the agent exchanges it for the credential.

The code never appears in the email. It only exists on the consent page, after an explicit approval. An agent with access to the user's inbox cannot approve its own request.

What the credential can do

Credentials are scoped. Agents get what onboarding needs and nothing else.

The credential acts as the user who approved it, inside their workspace. Organization settings, member management, and billing stay out of reach. Credentials expire after 30 days; agents re-register to renew.

Revocation

Three independent paths revoke agent access:

• The user can deny a pending request from the consent page.
• The agent can revoke its own credential by presenting it to the revocation endpoint.
• The agent platform can revoke every credential issued for a user by posting a signed logout token. One event from the platform invalidates all of that user's agent credentials at once.

Try it

Next steps

• swirls.ai/auth.md: the full registration contract with request and response shapes.
• OIDC Federation: workload authentication from your own identity provider.
• Swirls Cloud: managed runtime and Portal.