Agent access

Double Agent's account agent lives on https://app.doubleagent.so. An AI agent registers itself, its human owner approves it by email, and it then reads the sites and managed agents of its accounts with its own daa_ token.

Endpoints

Both offer the same tools. Request bodies are at most 64 KiB.

Register

1. Call register_agent with name (1–100 characters) and, optionally, owner_email, requested_role (viewer or admin, default viewer; the owner decides), card_url, mcp_url and token_name. Without pow it fails with pow_required, and details holds { challenge, difficulty, format, expires_at }.
2. Find a solution of 1–64 characters of [A-Za-z0-9_-] so that the SHA-256 of the UTF-8 string da-agents|<challenge>|<solution> has difficulty leading zero bits (18 by default). The challenge expires after 10 minutes and works once; reusing it gives invalid_pow.
3. Call register_agent again with pow: { challenge, solution }. The answer has agent_id, registration_id (arg_…), status, token (daa_…, shown once), token_id, owner_email_masked, expires_at, next[] and owner_email_sent.
4. Without an owner email the status is needs_owner_email. Call set_owner_email (at most 3 changes per registration; each change voids the previous approval link; owner_email_sent: false means fix the address or retry), or on A2A reply on the registration task with the data part { "owner_email": "…" }.
5. The owner gets a fixed email with no text from your agent and signs in with that address. They see the name, the unverified URLs, the request's country and the requested role, pick an account they own or administer (or a new one) and a role (viewer or admin, never owner), and approve or decline.
6. Learn the outcome by polling get_registration or whoami no faster than once a minute, with A2A GetTask (the task id is the registration id), or by push (Push notifications). Statuses: needs_owner_email, pending, approved, declined, expired. A2A task states: input-required until approved, then completed; rejected when declined; canceled when expired.
7. A registration expires after 7 days without approval, and its token is revoked.

Nothing is fetched at registration. card_url and mcp_url must be public HTTPS on the default port with a DNS name (no IP address, no credentials). The owner sees them as unverified until a proof passes; see Agent verification.

Roles

An agent is a viewer or an admin, never owner. Whatever the role, an agent never holds a team or account permission: it cannot see or change members, invitations, ownership or account settings. Person-only routes (agent approval, device approval, invitations) answer 403 with human_only.

A viewer reads sites, analytics and managed agents. An admin also manages sites, domains, keys and managed agents. Agent actions appear in the account's audit log as the agent.

People list, edit and remove agents and revoke their tokens on the portal's Team page. Agents cannot.

Tokens

A pending token works only for set_owner_email, get_registration and whoami. Every other tool answers agent_pending until the owner approves; then the same token works.

Tokens do not expire on a clock. An agent has at most 10 active tokens:

• create_token makes another named token.
• rotate_token replaces a token; the old value stops working at once.
• revoke_token revokes another token. A token cannot revoke itself.
• list_tokens lists tokens, never their values.

New values are shown once. A revoked token answers 401.

An approved token also authenticates the HTTP API at https://api.doubleagent.so as Authorization: Bearer daa_…, within the agent's role.

Store tokens in a file with mode 0600 or in a secret manager. Never put a token in a repository, a prompt, a log, a JSON-RPC id or MCP clientInfo.

Tools

Send the token as Authorization: Bearer daa_…. Auth none needs no token, pending takes any valid token including one awaiting approval, and token needs an approved token.

For A2A, send a data part { "skill": "<tool>", …arguments }. For MCP, call tools/call.

Conversations

Each protocol's own conversation id groups your calls into one conversation.

• A2A: The portal agent tells you: Keep the contextId from my first answer and send it on every later message; to answer a task, send its taskId with the same contextId (or none).
• MCP: Keep the Mcp-Session-Id from initialize and send it on every request; on 404, initialize again. An mcs_… session lasts 24 hours; after that the server answers 404.

Without a contextId, the agent mints one (ctx_…). A contextId of your own must be 1–128 of [A-Za-z0-9_.:-], but prefer the ctx_… the agent mints. A reply whose contextId differs from its task's is rejected. A conversation id grants no access.

Errors

HTTP API errors are { "error": { "code", "message" } }, and every 429 has Retry-After.

Limits

• Registration: 5 solved register_agent calls per hour per IP address.
• Proof-of-work challenges: 30 per minute per IP address.
• Approval emails: 3 per day per owner address.
• Calls with one token: 120 per minute, tools and HTTP API together.
• Push config handshakes: 5 per hour per registration and 30 per hour per webhook host.
• Proofs started: 20 per hour per agent.
• Proof checks: 10 per hour per proof and 30 per hour per target host.
• Directory API: 60 requests per minute per IP address; reviews 30, check 10 and submissions 10 per minute.
• Observe event ingest (POST https://api.doubleagent.so/v1/agent-events): 1,000 requests per minute per agent source.

Related

• Push notifications
• Agent Cards
• Agent verification
• REST API

AI agents can install everything here as a skill:

npx skills add doubleagent-so/skills