AgentID Browser Enrollment

AgentID browser enrollment lets a persistent browser create and retain its own non-extractable P-256 credential. An agent authorizes the enrollment with an existing AgentMail bearer API key, but that key is sent only to the AgentMail API. The browser creates the private key and never exports it.

AgentMail API keys are sent only to https://api.agentmail.to; AgentID never requests them.

The AgentID configuration document publishes the same fixed origins and endpoints for discovery. It is not an origin override: do not accept a different origin from runtime input.

Enrollment flow

1. Open an AgentID authorization transaction in a persistent browser.
2. When the page reports that enrollment is required, capture its machine action and the browser’s independently reported final URL from the same page observation. Do not combine an action from one page or frame with the URL from another.
3. Verify that the final URL’s origin is exactly https://auth.agentid.com. Also verify the action’s fixed fields and expiry.
4. Select the inbox from trusted AgentMail configuration; never use login_hint as the source of authority. If the action publishes a string login_hint, require the selected inbox to match it. A null action hint does not prove that the original authorization transaction omitted its hint; the API still checks the original value and may return 400.
5. Substitute the trusted inbox into the fixed endpoint template, then send {transaction_jti} with the bearer API key to exactly https://api.agentmail.to/v0/inboxes/{inbox_id}/browser-credentials/enrollments.
6. Keep the existing AgentID page open. It observes the pending intent, creates a non-extractable browser key, proves possession, and continues the same transaction.

The enrollment POST requires api_key_create. A new intent returns 202; an idempotent retry for the same pending transaction, inbox, and bearer key returns 200 with the same body:

1
{
2
  "status": "pending",
3
  "enrollment_id": "4d795cc3-ae87-4f84-85e3-4ad4ca656f44",
4
  "expires_at": 1787694600
5
}

This receipt contains no AgentID URL, token, cookie, or navigation instruction. Do not navigate away from the browser transaction in response to it.

An enrollment intent lasts at most five minutes and may expire sooner with its authorization transaction. An activated browser credential lasts at most 30 days and may expire sooner with its authorizing bearer API key. Remembered consent lasts 180 days. Treat every returned expires_at as authoritative and re-enroll before the browser credential expires.

Enrollment creation is limited to 20 intents per bearer API key per hour, 100 per organization per hour, and five live unused intents per bearer API key. A limit returns 429; honor its Retry-After header instead of retrying before the indicated time. Cancel an unused pending enrollment or let it expire to release a live-intent slot.

Browser activation is separately limited to 20 activations per authorizing bearer API key per UTC day. Hitting that limit can return 429 from the browser activation step after the enrollment POST succeeded. Honor Retry-After and wait for the daily window to reset; cancelling an enrollment does not reset the activation counter.

Create an enrollment with HTTP

The browser page exposes a machine action with the following shape. Read it only after obtaining the final page URL from the browser transport:

1
{
2
  "type": "agentid_enrollment_required",
3
  "issuer": "https://auth.agentid.com",
4
  "browser_origin": "https://auth.agentid.com",
5
  "agentmail_enrollment_endpoint": "https://api.agentmail.to/v0/inboxes/{inbox_id}/browser-credentials/enrollments",
6
  "transaction_jti": "AAAAAAAAAAAAAAAAAAAAAA",
7
  "transaction_expires_at": 1787694600,
8
  "login_hint": null,
9
  "login_hint_authoritative": false,
10
  "invariant": "AgentMail API keys are sent only to https://api.agentmail.to; AgentID never requests them."
11
}

login_hint is always present in the action but may be null. When it is a string, it is still non-authoritative and must match the trusted inbox selected by the caller. A null value means only that AgentID did not publish a safe-shaped hint; the server may still enforce a hint stored on the original authorization transaction.

These examples use ordinary authenticated HTTP. They validate the fixed endpoint template from the action, then substitute an inbox selected from trusted AgentMail configuration. They never follow an arbitrary URL supplied at runtime.

1
import re
2
import time
3
from urllib.parse import quote, urlsplit
4
5
import httpx
6
7
AGENTID_ORIGIN = "https://auth.agentid.com"
8
ENROLLMENT_ENDPOINT_TEMPLATE = (
9
    "https://api.agentmail.to/v0/inboxes/{inbox_id}/browser-credentials/enrollments"
10
)
11
INVARIANT = (
12
    "AgentMail API keys are sent only to https://api.agentmail.to; "
13
    "AgentID never requests them."
14
)
15
JTI = re.compile(r"^[A-Za-z0-9_-]{22}$")
16
17
18
def canonical_origin(url: str) -> str:
19
    parsed = urlsplit(url)
20
    if parsed.scheme != "https" or parsed.hostname is None:
21
        raise ValueError("Browser page is not HTTPS")
22
    port = "" if parsed.port in (None, 443) else f":{parsed.port}"
23
    return f"{parsed.scheme}://{parsed.hostname}{port}"
24
25
26
def create_browser_enrollment(
27
    *, source_url: str, action: dict, inbox_id: str, agentmail_api_key: str
28
) -> dict:
29
    # Capture source_url and action together from the same browser page.
30
    # source_url must come from the browser/automation transport, not the action.
31
    if canonical_origin(source_url) != AGENTID_ORIGIN:
32
        raise ValueError("Untrusted browser enrollment origin")
33
    if (
34
        action.get("type") != "agentid_enrollment_required"
35
        or action.get("issuer") != AGENTID_ORIGIN
36
        or action.get("browser_origin") != AGENTID_ORIGIN
37
        or action.get("agentmail_enrollment_endpoint")
38
        != ENROLLMENT_ENDPOINT_TEMPLATE
39
        or action.get("login_hint_authoritative") is not False
40
        or action.get("invariant") != INVARIANT
41
    ):
42
        raise ValueError("Invalid browser enrollment action")
43
44
    jti = action.get("transaction_jti")
45
    expires_at = action.get("transaction_expires_at")
46
    if not isinstance(jti, str) or JTI.fullmatch(jti) is None:
47
        raise ValueError("Invalid transaction_jti")
48
    if type(expires_at) is not int or expires_at <= int(time.time()):
49
        raise ValueError("Expired browser enrollment action")
50
51
    # inbox_id comes from trusted AgentMail configuration, not login_hint.
52
    login_hint = action.get("login_hint")
53
    if login_hint is not None and login_hint != inbox_id:
54
        raise ValueError("Trusted inbox does not match login_hint")
55
56
    enrollment_endpoint = (
57
        "https://api.agentmail.to/v0/inboxes/"
58
        f"{quote(inbox_id, safe='')}/browser-credentials/enrollments"
59
    )
60
    response = httpx.post(
61
        enrollment_endpoint,
62
        headers={"Authorization": f"Bearer {agentmail_api_key}"},
63
        json={"transaction_jti": jti},
64
        follow_redirects=False,
65
        timeout=10,
66
    )
67
    if response.status_code not in (200, 202):
68
        raise RuntimeError(f"Enrollment failed: {response.status_code}")
69
    return response.json()

Manage credentials and consent

Management requests use a bearer API key at https://api.agentmail.to. List operations require api_key_read; deletion and cancellation require api_key_delete.

List endpoints accept limit from 1 through 100 and a sealed page_token. They return count, the effective limit, an optional next_page_token, and the corresponding credentials, events, or consents array.

For rotation, enroll and verify a new browser credential, then revoke the old credential. There is no endpoint that extends a credential in place. A browser credential cannot outlive its authorizing bearer API key, and deleting or expiring that bearer key prevents the browser credential from authorizing new requests.

The browser’s Forget action deletes only local key material. It does not revoke the server credential or remembered application consent. Use the DELETE endpoints above for server-side revocation. Cancel applies only while an enrollment is pending and unexpired.

Consent behavior

AgentID shows an explicit Allow/Deny review on first use, after a material change to the requested scopes, callback, or trust configuration, when remembered consent expires, and when the client sends prompt=consent. An exact unexpired consent can be reused. With prompt=none, a transaction that cannot reuse consent returns consent_required to the client instead of opening an interactive approval.

Deleting a remembered consent does not delete the browser credential. It makes the next interactive authorization require review again.

Persistent browser support

Use a standard persistent Chromium profile. It supports enrollment, signing after a full browser restart, and re-enrollment after site data is cleared.

Do not promise persistence for private or incognito sessions. Safari and Safari Technology Preview remain unqualified until real-browser enrollment, full restart, signing, and site-data-clear recovery are recorded. A successful short test does not override WebKit’s documented seven-day eviction behavior for script-writable storage. Playwright WebKit is not a shipping Safari qualification. Embedded WebViews must be qualified in the real host application with its configured persistent data store and a full host restart; nonpersistent data stores are unsupported.

Migration from public-key authentication

Browser enrollment is the current path for persistent browser approval. The AgentID public-key flow remains supported during migration, and no deprecation date is being announced with this release.