Adding a Sign in with AgentID Button

Adding a Sign in with AgentID button takes two configuration values and one image. AgentID is the sign-in for AI agents from AgentMail, and it is standard OpenID Connect.

The job has two halves:

1. Configure the provider. In your auth platform, add a custom OpenID Connect provider with issuer https://auth.agentid.com and your client_id. That is a URL you control for the open tier, or the id from registration.
2. Add the button. On your login page, next to your Google and GitHub buttons, show the AgentID mark from https://www.agentid.com/brand/ and the text "Sign in with AgentID." Style it to match its neighbors and wire it to the same sign-in call your other providers use.

That is the whole job. The fastest way to do the first half is npx @agentmail/agentid-cli init in your project directory. The second half is copy and paste from below.

It is free for apps.

What does an agent see when it clicks the button?

An agent that clicks Sign in with AgentID sees what a person sees with Sign in with Google: a redirect to the provider, a short interaction, and a return to your app signed in.

That is also why adding the button to a website follows the same steps as adding Google. The redirect goes to https://auth.agentid.com/v0/authorize. What happens next depends on the agent:

• Enrolled browser: the browser produces a fresh one-time signature for this sign-in. A disclosure screen shows which app is asking and what it will receive, and the browser returns to your callback with an authorization code.
• Browser with no AgentID session: the page shows the agent one command that creates one, which is the one-time enrollment step.
• No browser at all: its owner can complete the sign-in from the AgentMail console, in the browser where the flow started.

A human who clicks it out of curiosity sees the same page and learns what AgentID is. That is intentional. The button on your login page is how AgentMail pays for a free product.

Step one: how do you configure your auth platform for AI agent authentication?

Configure your auth platform by adding AgentID as an OpenID Connect provider with the issuer and a client_id. Pick your platform below; each has a per-dashboard walkthrough in the docs, and the CLI handles all of them.

Or skip the dashboard:

npx @agentmail/agentid-cli init

Run it from the application you want to configure, with Node.js 20 or newer. The CLI does four things:

1. Detects the provider.
2. Registers a client. A browser opens for your organization to approve; there is no unattended bypass.
3. Writes the configuration.
4. Verifies it.

Press Enter at the scope picker for openid email profile, or add --owner-email if your app needs the human owner's address. npx @agentmail/agentid-cli doctor checks everything without changing anything.

The CLI configures your application to accept agents. It does not sign an agent in.

Two values are all any of these need:

• Issuer: https://auth.agentid.com
• Client ID: your client_id

Discovery at https://auth.agentid.com/.well-known/openid-configuration supplies the rest.

If you want the owner's email, register a client and request the owner_email scope. You can register with the CLI, the AgentID console, or one RFC 7591 call. Read the owner from /userinfo, not the id_token.

The full protocol reference is OIDC for AI agents: the complete guide.

Step two: what are the button assets?

The button assets are four variants of the AgentID mark, each as SVG and PNG, all free to use for a sign-in button. Prefer the SVG; the button is usually small and the SVG stays sharp.

All four are on the AgentID brand page.

Dashboard providers draw the button from a display name and, where the form has one, a logo URL.

• Display name: type AgentID.
• Logo field: where one exists, paste one of these URLs into it. The Auth0 Marketplace listing carries its own branding.
• Variant: pick the one that matches your login page's background, since a pasted URL cannot switch with the theme.

Step three: what does the button markup look like?

If you render your own buttons with Better Auth, Auth.js, or a custom client, copy the shape of the provider buttons you already have. A minimal version:

<button type="button" class="provider-button" onclick="signInWith('agentid')">
  <img src="https://www.agentid.com/brand/icon-black.svg" alt="" width="20" height="20" />
  <span>Sign in with AgentID</span>
</button>

The onclick calls whatever your other providers call:

• Supabase: supabase.auth.signInWithOAuth({ provider: 'custom:agentid' })
• Better Auth: the provider id is agentid.
• Clerk and Auth0: the platform's own components render the button once the connection is enabled, and you only need to make sure it appears in the list.

Three layout rules come from the brand page:

• Pair the mark with the name. Do not show the mark alone, so someone who has never seen it can tell what it does.
• Match the shape of the other providers. If Google and GitHub are full width with a left-aligned icon, do the same. A button that stands out from its neighbors reads as an advertisement rather than an option.
• Leave clear space. Keep at least half the mark's height clear around it, and never render it below 16px.

What are the Sign in with AgentID button guidelines?

The name reads AgentID: one word, no space, capital I and capital D, in running text, button labels, and code comments alike.

• Misspellings to avoid: "Agent ID," "AgentId," and "agentID."
• Never shortened to "Agent."

The verb around it is yours. "Sign in with AgentID," "Continue with AgentID," and "Log in with AgentID" are all fine. Use whichever your Google and GitHub buttons already use, so the three read as one set.

Use a mark from the set above unmodified: no recoloring, effects, rotation, or redrawing.

The mark identifies the sign-in option, not your product. It does not belong in your logo or anywhere it would suggest AgentID built or endorsed your app.

Where should the button go on the login page?

Put the Sign in with AgentID button beside the social sign-in buttons, in the same group, not in a separate "for agents" section.

There are two reasons:

• Agents find it. Agents driving a browser find it where they expect sign-in options to be.
• Humans see it. That is the point of the free product: someone who has never heard of AgentID learns that agents can have accounts here.

If your login has a "Continue with" group above the email form, it goes there.

If your API docs have an authentication section, add one sentence saying the app accepts Sign in with AgentID and link to your login page, so agents reading docs find the door.

What happens after the first sign-in?

After the first sign-in, your callback receives an ordinary authorization code, exchanges it at /v0/token, and gets an ES256-signed id_token with a stable sub and the agent's verified email.

1. Create the account keyed on sub.
2. Send your normal welcome email. The agent reads its inbox.
3. Store the owner. If you requested owner_email, call /v0/userinfo with the access token and store the owner on the account for per-human limits, as covered in how to verify the human behind an AI agent.
4. Get listed. List your app in the AgentID directory so agents looking for services that accept them find yours.

The longer relying-party guide, including the wire format and the security model, is how to let an AI agent sign in to your website.