# SiteGPT auth.md — Agent Auth

SiteGPT supports agent-first chatbot onboarding. An AI agent can create a temporary SiteGPT chatbot from a website URL, configure it with SiteGPT tools, and then hand the human one onboarding page where they can test and claim the chatbot.

Use this flow when the human wants to try SiteGPT before creating an account or before logging in to an existing account.

For existing SiteGPT users who already gave you a SiteGPT CLI profile, MCP connection, or API token, use the normal authenticated SiteGPT API/CLI/MCP flow instead.

## Discovery Metadata

Agents can discover this whole flow from standard metadata instead of
this document:

- `oauth-authorization-server` metadata: https://sitegpt.ai/.well-known/oauth-authorization-server
- `oauth-protected-resource` metadata: https://sitegpt.ai/.well-known/oauth-protected-resource
- Both documents carry an `agent_auth` block whose `register_uri`
  (https://sitegpt.ai/agent/auth) is the endpoint used in
  "Start Anonymous Registration" above, with per-type request shapes
  under `anonymous_supported`.
- MCP server manifest: https://sitegpt.ai/.well-known/mcp.json — also
  published in the official MCP registry as `io.github.sitegpt/sitegpt`.

## Supported Flows

| Flow | Status | Use when |
| --- | --- | --- |
| `anonymous` | Supported | The agent should create a temporary chatbot before the human signs in. |
| `identity_assertion` (AgentID) | Supported | The agent has its own AgentID (https://www.agentid.com) and signs in as itself. Start at `https://sitegpt.ai/auth/agentid`. |

## Pick A Method

Match the flow to your environment, in this order: shell available -> use
the SiteGPT CLI (`sitegpt onboarding start <url> --json`); HTTP only ->
POST the register endpoint below; MCP host -> connect
`https://sitegpt.ai/mcp` and `execute_write` the onboarding start
endpoint, then hand the returned `onboardingUrl` to the human (the
temporary credential does not ride the connector's OAuth grant — see
the appendix). The full decision guide is in the
[appendix](#appendix-full-reference).

The `identity_types_supported` enum is `anonymous` and
`identity_assertion` (provider: AgentID).
An agent with an AgentID signs in with standard OpenID Connect:
open `https://sitegpt.ai/auth/agentid`, approve the transaction by
signing its `jti` with the agent's registered P-256 key (the AgentID
contract at https://auth.agentid.com/docs/approve), and the callback
signs the agent in as a normal account under its verified AgentMail
address. The account works with every flow on this page, including
magic-link email — the agent's inbox is real. Unauthenticated API
calls answer 401 with a spec-shaped `WWW-Authenticate` challenge
naming the resource metadata.

## Register

One anonymous POST creates a temporary chatbot workspace - no account,
no key:

```bash
curl -X POST https://sitegpt.ai/agent/auth \
  -H "Content-Type: application/json" \
  -d '{"websiteUrl": "https://example.com"}'
```

The response returns a `credential` (scoped API token), a
`workspaceId`, a `registrationId`, and a status URI
(`https://sitegpt.ai/agent/auth/{registrationId}`). Full request
shape, aliases, and polling in the appendix.

## Claim

The human claims the chatbot from the onboarding page at
`https://sitegpt.ai/onboarding/preview/{workspaceId}` - they can test
it, then sign in to keep it; claiming converts the temporary workspace
into a real account-owned chatbot. Details in the appendix.

## Use Credential

The credential is a SiteGPT API token scoped to the temporary chatbot:

```bash
SITEGPT_API_TOKEN="<credential>" sitegpt chatbots get <chatbot-id> --json
```

or over HTTP: `Authorization: Bearer <credential>` against
`https://sitegpt.ai/api/v2`. Full command and endpoint examples in the
appendix.

## Errors

Structured JSON errors everywhere:

```json
{ "ok": false, "error": { "code": "VALIDATION_FAILED", "message": "..." } }
```

Retry `429` with backoff; `401` means the credential expired or the
workspace was deleted. The full code table is in the appendix.

## Revocation

Delete an unwanted temporary workspace before claim - the credential
and onboarding page stop working immediately:

```bash
SITEGPT_API_TOKEN="<credential>" sitegpt onboarding delete <workspace-id> --yes
```

---

## Appendix: Full Reference

## Choose Your Path By Capability

Match the flow to what your environment can actually do, in this order:

1. **You can run shell commands.** Use the SiteGPT CLI - it is the most
   reliable path, with structured `--json` output, `--wait` for ingestion, and
   a full command map via `sitegpt agent-guide`:

   ```bash
   sitegpt onboarding start https://example.com --json
   ```

   Run it once per site and reuse the returned ids. If the CLI is missing,
   `npm install -g @sitegpt/cli` (ask the human before installing).

2. **You can make raw HTTP requests.** POST to the registration endpoint
   documented below under "Start Anonymous Registration".

3. **Your environment cannot run commands or raw HTTP, but supports MCP
   connectors.** The check is what the environment CAN do, not what is
   already connected: if SiteGPT is not connected yet, connecting it is the
   first step. In Claude, install it from the connectors directory
   (https://claude.ai/directory/connectors/sitegpt); any other MCP client
   takes the server URL https://sitegpt.ai/mcp. Connecting opens SiteGPT's
   browser approval, where the human signs in or creates an account.

   Once connected, ask where the human wants the chatbot, then let the
   API decide capacity - do not compute quota arithmetic yourself. Plans
   assign quotas in more than one shape, so client-side math misroutes;
   the API's quota errors are the authority, and every one carries a
   `hint` naming the way out.

   - **The human wants it in this account**: attempt it directly with the
     MCP tools (`search` to find operations, `execute_read` /
     `execute_write` to run them). A chatbot built in the account needs
     no claim step. If a quota gate rejects a call, follow the error's
     `hint`. In particular, if creation succeeds but the first knowledge
     add fails with `CHATBOT_PAGES_LIMIT_REACHED`, the account has no
     training capacity: delete the empty chatbot
     (`DELETE /api/v2/chatbots/{chatbotId}?confirm=true`) and fall back
     to the anonymous flow.
   - **No account capacity, or a throwaway preview is wanted** (a new
     account without a plan never has training capacity): use the
     anonymous flow - `search` for "Start onboarding", then
     `execute_write` on `POST /api/v2/onboarding/agent/start` with
     `{ "websiteUrl": "https://example.com" }` (no authentication
     required), and give the human the returned `onboardingUrl` - that
     page shows training progress and hosts the claim flow.

   For an early routing signal before attempting, `execute_read` on
   `GET /api/v2/limits` (`data.available.pagesQuota`, `data.chatbots`)
   and `GET /api/v2/me` (`data.user.quotas.chatbotsQuota`) approximate
   capacity. They measure quota allocation, which does not cover every
   plan shape - treat them as a hint, and the API's errors as the
   verdict.

   Note: for the anonymous flow, starting the workspace is the ONLY step
   available over the MCP bridge. Every follow-up call - status, claim,
   delete, and the whole build workflow (knowledge, persona, instructions,
   settings) - authenticates with the temporary credential, but the bridge
   signs requests with the connected account's grant, and the temporary
   chatbot belongs to a separate temporary user that grant cannot touch.
   Do not attempt the build workflow; hand over the onboarding URL as soon
   as the start call returns. After the human claims the chatbot into the
   connected account, it becomes manageable over MCP like any other
   chatbot.

   Today the claim finishes in the human's browser: an agent or CLI can
   START a claim over the API (`claimUrl`, with the email, plan, and
   interval the human provided), but clicking the magic link and any
   payment step remain the human's - they prove mailbox ownership and
   authorize billing through a checkout that does not yet have
   agent-native rails. Treat that as the current boundary of the agent's
   role in creating a NEW account, not as a rule: agent-completable
   claim is planned - verified identity assertion in place of the
   magic-link click (watch `identity_types_supported` in the OAuth
   authorization server metadata at
   `/.well-known/oauth-authorization-server` for `identity_assertion`),
   and delegated payment via agentic commerce protocols. For chatbots in
   an existing connected account, the agent already does everything over
   MCP and the API with no human step.

4. **No shell, no HTTP, and no MCP support.** You cannot execute this flow.
   Give the human the website URL you would have used and send them to
   https://sitegpt.ai to start a free trial themselves, and offer to help
   them configure the chatbot once they have access.

## Start Anonymous Registration

Endpoint:

```http
POST https://sitegpt.ai/agent/auth
Content-Type: application/json
```

Request:

```json
{
  "flow": "anonymous",
  "websiteUrl": "https://example.com",
  "agentName": "Claude",
  "agentClientId": "claude-web"
}
```

Required fields:

- `websiteUrl`: the public website the chatbot should be created for.

Optional fields:

- `flow`: use `anonymous`. If omitted, SiteGPT treats it as `anonymous`.
- `agentName`: display name of the agent or tool creating the chatbot.
- `agentClientId`: stable client identifier for the agent environment, if available.

Snake-case aliases are also accepted for compatibility: `website_url`, `agent_name`, and `agent_client_id`.

Response:

```json
{
  "ok": true,
  "data": {
    "registrationId": "workspace_id",
    "registrationType": "anonymous",
    "credentialType": "api_key",
    "credential": "sgpt_xxxxxxxxx",
    "credentialExpiresAt": "2026-05-31T00:00:00.000Z",
    "resource": "https://sitegpt.ai/api/v2",
    "apiBase": "https://sitegpt.ai",
    "mcpUrl": "https://sitegpt.ai/mcp",
    "workspaceId": "workspace_id",
    "chatbotId": "chatbot_id",
    "onboardingUrl": "https://sitegpt.ai/onboarding/preview/workspace_id",
    "statusUrl": "https://sitegpt.ai/agent/auth/workspace_id",
    "apiStatusUrl": "https://sitegpt.ai/api/v2/onboarding/workspaces/workspace_id",
    "claimUrl": "https://sitegpt.ai/api/v2/onboarding/workspaces/workspace_id/claim",
    "scopes": [
      "account:read",
      "chatbots:read",
      "chatbots:write",
      "knowledge:read",
      "knowledge:write",
      "personas:read",
      "personas:write",
      "instructions:read",
      "instructions:write",
      "settings:read",
      "settings:write",
      "starters:read",
      "starters:write",
      "followups:read",
      "followups:write",
      "conversations:read",
      "conversations:write"
    ]
  }
}
```

Treat `credential` as an opaque secret. Store it only for the active task and do not print it back to the human unless explicitly asked.

Use `onboardingUrl` as the human-facing preview and claim page.

`claimUrl` is an API endpoint for agents or CLI clients that are starting a claim after the human has provided an email, plan, and interval. Do not send `claimUrl` to the human as the page to open.

## Use The Credential

The returned credential is a SiteGPT API token scoped to the temporary chatbot.

Use it with the SiteGPT CLI:

```bash
SITEGPT_API_TOKEN="<credential>" sitegpt chatbots get <chatbot-id> --json
SITEGPT_API_TOKEN="<credential>" sitegpt knowledge sitemap add --chatbot <chatbot-id> https://example.com/sitemap.xml --json
SITEGPT_API_TOKEN="<credential>" sitegpt onboarding status <workspace-id> --json
```

Or use it with the API:

```http
Authorization: Bearer <credential>
```

MCP-connected agents without shell or HTTP access skip this section
entirely: the bridge cannot use the temporary credential, so the onboarding
page linked from `onboardingUrl` is the human's path to status and claim,
and the chatbot becomes manageable over MCP only after it is claimed.

The token is limited to the onboarding chatbot. It is intended for setup work such as adding knowledge, setting personas and instructions, configuring appearance, and testing conversations.

## Build Workflow

After registration:

1. Inspect the target website.
2. Create or verify knowledge sources.
3. Add the best available sitemap or website knowledge.
4. Configure persona, instructions, starters, follow-up prompts, and visual settings.
5. Test the chatbot with realistic visitor questions.
6. Call the status endpoint and inspect the setup checklist.
7. Share the onboarding URL when the chatbot is ready for human review.

Status endpoint:

```http
GET https://sitegpt.ai/agent/auth/{registrationId}
Authorization: Bearer <credential>
```

The status response includes:

- `workspace`
- `setupChecklist`
- `onboardingUrl`
- `claimUrl`
- `nextAction`
- `claimStatus`
- `credentialExpiresAt`

## Claim Workflow

The human claims the chatbot from the onboarding page:

```text
https://sitegpt.ai/onboarding/preview/{workspaceId}
```

The page lets the human:

- Test the chatbot.
- See setup status.
- Choose the account that should own the chatbot.
- Start a SiteGPT free trial if they are new.
- Claim directly if they are an existing subscriber with available chatbot capacity.

After claim:

- The chatbot becomes a normal SiteGPT chatbot under the claimed account.
- The temporary agent credential remains scoped only to that chatbot.
- The credential keeps its original expiry.
- The user can revoke it later from the SiteGPT Agents page.

## Existing SiteGPT Users

If the human already has a SiteGPT account, prefer one of these flows:

- Ask them to connect SiteGPT through MCP.
- Ask them to run `sitegpt login`.
- Ask them to create a scoped API token from the SiteGPT Agents page.

If an existing subscriber uses anonymous onboarding anyway, they should open the onboarding URL while signed in to the same SiteGPT account and claim from that page.

## Limits

Anonymous onboarding workspaces are temporary and constrained:

- One temporary chatbot.
- Limited pages and test messages.
- Chatbot-scoped token only.
- No billing, member, or token-management scopes.
- Expiry is returned as `credentialExpiresAt` and `workspace.expiresAt`.

## Delete A Temporary Workspace

If the human does not want the temporary chatbot, the agent can delete it before claim:

```bash
SITEGPT_API_TOKEN="<credential>" sitegpt onboarding delete <workspace-id> --yes
```

After deletion, the onboarding page and token are no longer usable.

## Errors

SiteGPT returns structured JSON errors:

```json
{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request body is not valid"
  },
  "meta": {
    "requestId": "..."
  }
}
```

Common errors:

- `VALIDATION_FAILED`: request body is missing required fields.
- `WEBSITE_URL_INVALID`: website URL is not a valid public URL.
- `WEBSITE_URL_HOST_NOT_ALLOWED`: private, localhost, or internal host was rejected.
- `REGISTRATION_NOT_FOUND`: registration ID was not found for this credential.
- `ONBOARDING_TOKEN_REQUIRED`: status or delete was called without the onboarding credential.
- `TOKEN_SCOPE_NOT_ALLOWED`: credential does not have the required scope.

## Documentation

- CLI guide: https://sitegpt.ai/docs/cli/overview
- Use CLI with agents: https://sitegpt.ai/docs/cli/use-with-ai-agents
- API reference: https://sitegpt.ai/docs/api-reference/v2/getting-started
- OpenAPI: https://sitegpt.ai/api/v2/openapi.json
- MCP server: https://sitegpt.ai/docs/cli/mcp-server
