Skip to main content
Sign in with Agent Loadout is a standard OpenID Connect provider. If your app already accepts Sign in with Google, it accepts agents with two configuration values: the issuer and a client id.

​
Issuer and discovery

The discovery document lists authorization_code as the only grant type, code as the only response type, S256 as the only PKCE method and ES256 as the only signing algorithm. There are no refresh tokens and no end_session_endpoint: the sign-in proves who the agent is, and your app’s session takes over from there.

​
Client tiers

No registration. Your client_id is an HTTPS origin you control, for example https://yourapp.com. The redirect URI must sit on that origin, PKCE with S256 is mandatory, and the token request uses token_endpoint_auth_method none. Open clients may request openid, email and profile. Because the origin is the trust anchor, an open client cannot run on http://localhost; register an application for local development.

​
The flow on the wire

1

Redirect the agent

The browser lands on a waiting page where the agent approves with its own token, or a member approves in the dashboard. Requests can be approved for ten minutes.
2

Receive the code

Agent Loadout redirects to your redirect_uri with code, state and iss (RFC 9207). Codes are single-use and valid for 60 seconds.
3

Exchange the code

Registered applications send their secret as HTTP Basic credentials or as client_secret. The response carries id_token, access_token, token_type, expires_in (600) and scope.
4

Verify and create the account

Verify the id_token, create or look up the account by sub, and store the owner if you requested it.

​
Scopes and claims

Scopes are space separated. A request without scope means openid email. Registered applications also receive a scope claim naming what was granted. Claims that were not granted are omitted, never nulled: test for presence. A decoded id_token for a registered application that asked for everything:
sub identifies the agent and stays the same at every app; a deleted and recreated agent gets a new one. owner_sub identifies the organization and is shared by all its agents, so it is the right key for per-owner limits when you do not want to hold anyone’s email address. Neither can be matched to Agent Loadout ids.

​
Letting agents start the sign-in

Set a login start URL on a registered application (OpenID Connect initiate_login_uri). When an agent starts a sign-in from its side, its browser arrives there with iss=https://id.agent-loadout.com and login_hint=<the agent's sub>; your handler begins your normal sign-in with Agent Loadout as the provider, and the sign-in completes without anyone acting, because the agent granted your app beforehand. Most auth libraries have a one-line way to start a provider sign-in; point the URL at a route that calls it. List the application in the directory with a description and website so agents find it; the directory marks apps with a login start URL as ones agents can sign in to directly.

​
Verifying the token

  1. Fetch https://id.agent-loadout.com/jwks.json and select the key by kid. Keys rotate every 90 days and a retired key stays published for two days, so caching by kid is safe.
  2. Verify the ES256 signature.
  3. Check that iss is exactly https://id.agent-loadout.com and aud is exactly your client_id.
  4. Check that exp is in the future, and that nonce matches if you sent one.
GET /userinfo with the access token as a Bearer token returns the same claims, re-read live: an archived agent, a lost inbox or a revoked approval ends there before the token expires. Keep agent sessions short and re-read /userinfo before the actions that matter most.

​
The owner guarantee

A registered application that requested owner_email never receives a successful sign-in without it. When the agent’s token lacks identity:share_owner, the agent cannot approve on its own and an owner or admin of its workspace approves in the dashboard. A workspace without a claimed owner cannot share one at all.

​
Capping sign-ups per owner

Set Maximum sign-ups per owner on a registered application. Agent Loadout counts the agents of one organization that hold an approval for your app and refuses the next one with error=access_denied&error_description=signup_limit_reached on your callback, before the account exists. 0 pauses new agents while existing ones keep signing in.

​
Setting up common auth platforms

The fastest way is the CLI: npx @agent-loadout/cli app init in your project detects the platform, registers the application, writes the client values into .env.local and prints the remaining steps; app doctor checks the result. See CLI setup. By hand:
Add a Custom OpenID Connect provider under SSO connections with issuer https://id.agent-loadout.com, your client id and secret, and scopes openid email profile. Clerk keeps standard claims on the user; fetch owner_email from /userinfo in your callback and store it yourself.

​
Revocation

An agent or a member of its workspace can forget an app at any time, and members can revoke the sign-in keys that stand for the agent. Both stop new sign-ins; sessions your app already issued last as long as your app decides. Keep agent sessions short and re-read /userinfo before sensitive actions to notice sooner.

​
Button

Show the Agent Loadout mark next to your other sign-in buttons with the text Sign in with Agent Loadout, in the same shape and width as your Google and GitHub buttons, and wire it to the same sign-in call. The mark in three variants, HTML and React snippets and the usage rules are at agent-loadout.com/brand.