AgentID Sign-In

AgentID lets agents sign in to providers using an AgentMail inbox as their identity. Start a sign-in with a provider, or authorize one that is already waiting, then manage the resulting credential through the API Keys endpoints.

A sign-in credential has type: "public_key" and a status of pending or active. AgentMail returns its api_key_id, which you use to check activation, update permissions, or revoke access.

Before you start

• Choose an inbox you control and a bearer API key that can access it.
• Enable provider_connect on that key to connect providers and authorize sign-ins. This permission defaults to false on newly created bearer keys.
• Enable api_key_read to check key status, api_key_update to change permissions, and api_key_delete to revoke a key.
• Use the US API at https://api.agentmail.to for these sign-in flows.

Install the CLI with npm install -g agentmail-cli@latest, or the TypeScript SDK with npm install agentmail@latest. Set AGENTMAIL_API_KEY in your environment.

Connect to a provider

Find a provider with agentmail providers list or agentmail providers search --q "provider name". Use its returned provider_id when connecting:

agentmail providers connect \
  --provider-id d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32 \
  --inbox-id agent@example.com

import os
import uuid
import httpx
response = httpx.post(
    "https://api.agentmail.to/v0/providers/d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32/connect",
    headers={"Authorization": f"Bearer {os.environ['AGENTMAIL_API_KEY']}",
             "Idempotency-Key": str(uuid.uuid4())},
    json={"inbox_id": "agent@example.com"},
    timeout=30,
)
response.raise_for_status()
connection = response.json()
print(connection["magic_url"], connection["api_key_id"])

Open the returned magic_url in the client that will complete the sign-in. It is single-use and valid for five minutes; expires_at reports its expiry. Save api_key_id to check activation. Keep the URL private and avoid logging it in production.

The CLI supplies an idempotency key automatically and reuses it across retries. Pass --idempotency-key to reuse the same attempt across manual runs. For HTTP and SDK requests, keep the same Idempotency-Key header when retrying the same connect attempt.

You can omit inbox_id when your API key is already scoped to the inbox.

Authorize a pending sign-in

If an AgentID sign-in is already waiting, use Authorize Inbox with the auth_token supplied by that sign-in. Select the inbox from your own trusted configuration.

Set AGENTID_AUTH_TOKEN to that verified token, then authorize the inbox:

agentmail inboxes authorize \
  --inbox-id agent@example.com \
  --auth-token "$AGENTID_AUTH_TOKEN"

import os
import httpx
response = httpx.post(
    "https://api.agentmail.to/v0/inboxes/agent%40example.com/authorize",
    headers={"Authorization": f"Bearer {os.environ['AGENTMAIL_API_KEY']}"},
    json={"auth_token": os.environ["AGENTID_AUTH_TOKEN"]},
    timeout=30,
)
response.raise_for_status()
key = response.json()
print(key["api_key_id"], key["status"])

The response is the pending public-key credential. Continue the same sign-in so the client can activate it. Repeating authorization with the same token, inbox, and bearer key returns the same credential; this endpoint does not need a separate idempotency key.

Accept a provider’s disclosure

To accept the provider’s disclosure on the agent’s behalf, add accept_disclosure: true to the connect or authorize request. The TypeScript field is acceptDisclosure: true; the CLI flag is --accept-disclosure true.

If the provider requests the owner’s name or email, the authorizing key also needs provider_share_owner. Without disclosure acceptance, complete the review presented during sign-in.

Check activation

Use the api_key_id returned by either flow:

agentmail api-keys get --api-key-id 4d795cc3-ae87-4f84-85e3-4ad4ca656f44

import os
import httpx
response = httpx.get(
    "https://api.agentmail.to/v0/api-keys/4d795cc3-ae87-4f84-85e3-4ad4ca656f44",
    headers={"Authorization": f"Bearer {os.environ['AGENTMAIL_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json().get("status"))

A single check reads the current status. Repeat with a delay while it is pending, stopping at expiry or an error. active means the key is ready to sign in as the inbox. Use List Provider Accounts to inspect accounts at the provider.

Manage sign-in keys

List responses contain api_keys, count, and an optional next_page_token. Continue with page_token (CLI: --page-token) until no token remains, even if an intermediate page is empty.

Sign-in keys carry provider_connect and provider_share_owner, copied from the creating bearer key and enforced independently. Change them through Update API Key. Deleting or changing the creating bearer key does not revoke the sign-in key.

An active sign-in key expires 30 days after activation. To rotate, create and activate a replacement, then delete the old key. Deleting a pending key cancels it; deleting an active key revokes it. There is no bulk revocation endpoint.

Credential lifetimes

A sign-in involves several objects with separate lifetimes. Ending one does not end the others.

The two long lifetimes are different objects. A 30-day sign-in key is a credential; a 180-day remembered approval is consent. A remembered approval does not prove a key is still usable, and revoking a key does not clear the approval. There is no endpoint to revoke a remembered approval.

Clear a session in the browser

The browser that completed a sign-in keeps the private half of its sign-in key as a saved session. To see and clear those sessions, open https://auth.agentid.com/sessions in that browser and choose to forget the session there. The page lists only the sessions saved in the browser that opens it, so a different browser or profile shows none.

Clearing a session there removes the sign-in material from that browser only. The key stays active on AgentMail until it expires or you revoke it; to revoke it, delete its key with DELETE /v0/api-keys/{api_key_id} as in the table above. Providers keep the sessions they issued until those expire or you sign out there.

I revoked a key, but an agent is still signed in at a provider

Revocation stops new sign-ins with that key. It does not end sessions the provider already issued. AgentID sends no revocation webhook and no back-channel logout, an ID token already issued stays valid until it expires ten minutes after issue, and the provider decides its own session length. Sign out at the provider, or wait for that session to expire. A provider that re-reads AgentID’s UserInfo endpoint inside those ten minutes sees the revocation sooner.