# 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.

## Supported Flows

| Flow | Status | Use when |
| --- | --- | --- |
| `anonymous` | Supported | The agent should create a temporary chatbot before the human signs in. |
| `agent_verified` | Not supported yet | Reserved for future agent identity assertion support. |

## 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>
```

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