# AgentLine Sign-Up and API Keys

Use this when the agent has no `AGENTLINE_API_KEY`. Keys look like
`al_live_...`; legacy `sk_live_...` keys still work. If the key is already set,
skip this page.

Pick one path:

1. **Email OTP**: any inbox the agent can read (the human's, its own, or an
   AgentMail inbox). Works headless.
2. **AgentID**: an AgentMail inbox plus AgentID signing material.
3. **Human handoff**: ask the human to sign in at
   https://agentline.cloud and hand over a key.
4. **No signup**: pay from a wallet and use an `agent_token`. See
   https://agentline.md/prepaid.md

The verified email string is the account. The same string always resolves to
the same account, so an agent and a human who sign in with it share one
account. A human Gmail and an AgentMail inbox are different accounts.

## Email OTP

Request a code:

```bash
curl -s -X POST https://api.agentline.cloud/v1/auth/otp \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
```

Read the code from the inbox (or ask the human for it), then verify:

```bash
curl -s -X POST https://api.agentline.cloud/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","otp":"123456"}' > /tmp/al_verify.json
export AGENTLINE_API_KEY="$(jq -r .api_key /tmp/al_verify.json)"
rm /tmp/al_verify.json
```

The response holds `api_key` (shown once), `account_id`, and the balance. Write
the key from the raw HTTP body; do not pass the secret through the model. New
accounts start at $0. Add credit at the dashboard before buying a number.

Limits: 3 OTP requests per email, 5 per IP, and 5 verify attempts per email per
10 minutes.

## AgentID

Requires a client that can open the waiting page and AgentMail signing material.
If `start` returns `404`, AgentID is disabled: use OTP.

1. Start. `login_hint` is optional and must be the inbox exactly as registered
   (do not lowercase it):

   ```bash
   curl -s -X POST https://api.agentline.cloud/v1/auth/agentid/start \
     -H "Content-Type: application/json" \
     -d '{"login_hint":"my-agent@agentmail.to"}'
   ```

   Returns `authorize_url`, `session_id`, and `poll_interval`.
2. Open `authorize_url`. The waiting page shows a 22-character `jti`. Do not
   scrape AgentID HTML. The AgentLine callback page never shows the key.
3. Approve with `POST https://api.auth.agentid.com/v0/authorize/approve`
   (`typ: agentid-approval+jwt`). `inbox_id` must match byte for byte,
   including case. Docs: https://auth.agentid.com/docs/approve
4. Poll every `poll_interval` seconds:

   ```bash
   curl -s -X POST https://api.agentline.cloud/v1/auth/agentid/poll \
     -H "Content-Type: application/json" \
     -d '{"session_id":"..."}'
   ```

   | Response | Meaning |
   |---|---|
   | `202` pending | Keep polling. |
   | `200` with `api_key` | Success. Write the key from the raw body. |
   | `200` `already_delivered`, `401`, `410` | Terminal. Stop polling this session. |

   After a terminal response, recover with `POST /v1/auth/keys` (if another key
   works), the human at agentline.cloud, or a new `start`.

Do not use the AgentID `owner_email` as the AgentLine account email.

## Manage Keys

```bash
# Mint another key
curl -s -X POST https://api.agentline.cloud/v1/auth/keys \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"

# List keys (the current one is marked)
curl -s https://api.agentline.cloud/v1/auth/keys \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"

# Revoke a key
curl -s -X DELETE https://api.agentline.cloud/v1/auth/keys/KEY_ID \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

You cannot revoke the key that authenticates the request. To rotate, mint a new
key, switch to it, then revoke the old one.

## First Check

```bash
curl -s https://api.agentline.cloud/v1/billing/balance \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

Continue with https://agentline.md/agents.md

AgentLine: https://agentline.cloud | API: https://api.agentline.cloud | All guides: https://agentline.md