agentid

AgentID: Accounts at Apps

AgentID lets an agent create an account at a third-party service, and sign back in later, using an AgentMail inbox as its identity. No password and no sign-up form: the inbox address is the account's email, and the app's mail arrives in that inbox. An app is a service in the AgentID marketplace, such as a scraping, search, or database API. An account is one inbox signed in at one app.

What users ask for

The goal is almost never the sign-in itself. It is a working account the agent can use, usually for an API key. Carry the job through to Finish the job.

Create an account

1. Find the app.

   • The user named the app: call get_app with its slug, the name lowercased without spaces or punctuation (firecrawl). A catalog app resolves in one call.
   • The slug 404s: call search_apps with the name. One match: use it. Several: show name, description, and ID, and ask. Never pick between look-alike names yourself. No match: see Not on AgentID.
   • The user gave an app ID: call get_app with it. List, search, and slugs cover only the curated catalog, but any registered app resolves by ID and can be connected once it has a sign-in entry point.

   From here on, pass the appId that get_app returned. list_accounts and connect_app also accept the slug, but the ID is permanent: use it in anything you store or report.

2. Pick the inbox that will own the account. The inbox is the agent's identity at the app.

   • The user named one: use it.
   • The organization has one inbox (list_inboxes): use it and say which.
   • Several: ask, and suggest a dedicated agent inbox over a person's.
   • None: offer to create one for the agent with create_inbox, then continue.

3. Check for an existing account. Call list_accounts with the appId and page until nextPageToken is absent.

   • This inbox already has one: this is a sign-in, not a new account. Say so and continue with Sign back in.
   • Another inbox has one: prefer signing in with that inbox over creating a second account, and say why. Apps can cap sign-ups per organization.
   • ownerSignupLimit on get_app is a hint, not a count to check against. 0 means new sign-ups are paused, so use an inbox that already has an account. Otherwise do not work out the headroom from list_accounts: the cap counts every inbox that ever signed up, including disabled accounts that list_accounts does not show. Try the connect, and let its limit error decide.

4. Show what the user is agreeing to: app name and description, terms and privacy links from get_app, and the inbox. An unlisted app returns only its ID, plus its name when one is registered, with no updatedAt; say it is not a reviewed catalog entry. If the user named both the app and the inbox, that request is the go-ahead; if you inferred either one, confirm first.

5. Call connect_app with appId and inboxId. inboxId can be omitted only when the credential is scoped to one inbox.

6. Hand off the sign-in URL. The response has magicUrl, expiresAt, and apiKeyId. Open magicUrl in the browser that should hold the sign-in:

   • If you control a browser, open it there. That browser keeps the agent's session at the app.
   • Otherwise give the link to the user and say what happens: it opens auth.agentid.com, may ask them to accept what the app will receive, then lands them in the app signed in as the inbox, with the account created. It works once, within five minutes. Their browser then holds the agent's session.

7. Confirm with list_accounts for that appId: the inbox should appear with a fresh lastSignedInAt. If it does not, the browser sign-in has not finished. Do not call connect_app again until the earlier URL has expired.