> ## Documentation Index
> Fetch the complete documentation index at: https://sitegpt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and scopes

> Understand SiteGPT CLI authentication, scoped tokens, access levels, token management, and least-privilege setup.

The CLI authenticates with scoped SiteGPT API tokens. Tokens are bearer credentials, stored locally by profile, and sent to `/api/v2` routes.

## Authentication methods

<Tabs>
  <Tab title="OAuth device login">
    Recommended for humans and local AI assistants:

    ```bash theme={null}
    sitegpt login
    ```

    OAuth device login opens a browser approval page and creates a scoped token after you approve access. The CLI uses `client_id=sitegpt-cli` with SiteGPT's OAuth device authorization endpoints.
  </Tab>

  <Tab title="Existing token">
    Useful for CI, servers, and environments where browser approval is not available:

    ```bash theme={null}
    sitegpt login --token <sitegpt-api-token>
    ```

    You can create the token manually in the SiteGPT dashboard from **Agents** → **Create token**, then copy the token and save it with `sitegpt login --token`.
  </Tab>

  <Tab title="Environment variable">
    Useful for one-off scripts:

    ```bash theme={null}
    SITEGPT_API_TOKEN=<sitegpt-api-token> sitegpt chatbots list
    ```

    Environment variables override the saved profile for that command.
  </Tab>
</Tabs>

## Manual dashboard-token login

Manual token login is useful when you want to choose permissions in the dashboard first, then connect the CLI afterward.

<Steps>
  <Step title="Create a token in the dashboard">
    Open the SiteGPT dashboard, go to **Agents**, click **Create token**, and choose the access level, scopes, and chatbot access.
  </Step>

  <Step title="Copy the token">
    Copy the plaintext token immediately. SiteGPT stores only a secure hash and cannot show the same token again.
  </Step>

  <Step title="Save it in the CLI">
    ```bash theme={null}
    sitegpt login --token <sitegpt-api-token>
    ```
  </Step>

  <Step title="Use a named profile when needed">
    ```bash theme={null}
    sitegpt login --profile knowledge-agent --token <sitegpt-api-token>
    sitegpt --profile knowledge-agent whoami
    ```
  </Step>
</Steps>

Creating a token does not automatically switch the CLI to that token. You must run `sitegpt login --token <token>` or set `SITEGPT_API_TOKEN` for one-off commands.

## OAuth device flow for agents

`sitegpt login` uses the OAuth Device Authorization Grant. This is the recommended browser-approved flow for local CLIs and personal AI agents because it does not require pasting an API token into chat.

The first-party CLI uses this public client identifier:

```text theme={null}
client_id=sitegpt-cli
```

`client_id` identifies the application requesting access. It is not a secret, and it is the same for all users of the SiteGPT CLI.

Discovery endpoints:

```text theme={null}
https://sitegpt.ai/.well-known/oauth-authorization-server
https://sitegpt.ai/.well-known/oauth-protected-resource
https://sitegpt.ai/.well-known/oauth-protected-resource/api/v2
```

OAuth endpoints:

```text theme={null}
POST https://sitegpt.ai/oauth/device_authorization
POST https://sitegpt.ai/oauth/token
```

For the full protocol shape, request fields, response fields, and polling errors, see [OAuth device flow](/cli/oauth-device-flow).

## Access levels

| Access level              | How to request                  | Best for                                                                 |
| ------------------------- | ------------------------------- | ------------------------------------------------------------------------ |
| Standard CLI access       | `sitegpt login`                 | Most day-to-day CLI usage without token, billing, or integration writes. |
| Full account access       | `sitegpt login --full-access`   | Trusted local workflows that need broad SiteGPT management.              |
| Custom access             | `sitegpt login --scope <scope>` | Specialized agents and automation with least-privilege tokens.           |
| Chatbot-restricted access | `sitegpt login --chatbot <id>`  | Agents that should only operate on selected chatbots.                    |

<Note>
  Token issuance is role-aware. A user can only create tokens for scopes and chatbots they are allowed to manage in the dashboard.
</Note>

For personal AI assistants, use a dedicated named profile and give the agent only the scopes it needs. See [Use with AI agents](/cli/use-with-ai-agents) for setup examples.

## Available scopes

| Resource               | Read                 | Write                 | Delete                 |
| ---------------------- | -------------------- | --------------------- | ---------------------- |
| Account                | `account:read`       | `account:write`       | -                      |
| Billing                | `billing:read`       | `billing:write`       | -                      |
| API tokens             | `tokens:read`        | `tokens:write`        | -                      |
| Chatbots               | `chatbots:read`      | `chatbots:write`      | `chatbots:delete`      |
| Knowledge              | `knowledge:read`     | `knowledge:write`     | `knowledge:delete`     |
| Personas               | `personas:read`      | `personas:write`      | `personas:delete`      |
| Instructions           | `instructions:read`  | `instructions:write`  | `instructions:delete`  |
| Settings               | `settings:read`      | `settings:write`      | -                      |
| Conversation starters  | `starters:read`      | `starters:write`      | `starters:delete`      |
| Conversation followups | `followups:read`     | `followups:write`     | `followups:delete`     |
| Conversations          | `conversations:read` | `conversations:write` | `conversations:delete` |
| Leads                  | `leads:read`         | `leads:write`         | `leads:delete`         |
| Members                | `members:read`       | `members:write`       | `members:delete`       |
| Integrations           | `integrations:read`  | `integrations:write`  | -                      |

## Token commands

```bash theme={null}
sitegpt tokens list
sitegpt tokens list --include-revoked
sitegpt tokens create --name "Docs agent" --scope account:read --scope chatbots:read
sitegpt tokens create --name "Knowledge updater" --chatbot <chatbot-id> --scope knowledge:read --scope knowledge:write
sitegpt tokens rotate <token-id>
sitegpt tokens revoke <token-id>
```

### Create options

| Option                     | Description                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `--name <name>`            | Token name. Required.                                                                 |
| `--scope <scope>`          | Scope to grant. Required and repeatable.                                              |
| `--chatbot <chatbot-id>`   | Restrict token to selected chatbots. Repeatable. Defaults to all accessible chatbots. |
| `--expires-in-days <days>` | Relative expiration. Valid range: `1-365`. Default: `90`.                             |
| `--expires-at <iso-date>`  | Absolute expiration. Cannot be combined with `--expires-in-days`.                     |

Reference: [token scopes](/cli/command-reference#token-scopes) and [API token commands](/cli/command-reference#api-tokens).

### Token lifecycle

Newly created and rotated tokens are shown once:

```bash theme={null}
sitegpt tokens rotate <token-id>
```

Store the plaintext token immediately. SiteGPT only stores a secure hash and cannot show the exact token again.

## Least-privilege examples

Read-only chatbot inventory:

```bash theme={null}
sitegpt login \
  --profile inventory \
  --scope account:read \
  --scope chatbots:read
```

Knowledge-only updater for one chatbot:

```bash theme={null}
sitegpt login \
  --profile knowledge-bot \
  --chatbot <chatbot-id> \
  --scope account:read \
  --scope chatbots:read \
  --scope knowledge:read \
  --scope knowledge:write
```

Support queue agent:

```bash theme={null}
sitegpt login \
  --profile support-agent \
  --chatbot <chatbot-id> \
  --scope account:read \
  --scope chatbots:read \
  --scope conversations:read \
  --scope conversations:write \
  --scope leads:read \
  --scope leads:write
```

## Security notes

* Do not commit `~/.config/sitegpt/config.json`.
* Prefer chatbot-restricted tokens for agents.
* Use `--json` for automation so scripts do not scrape human tables.
* Rotate tokens after demos, tests, and shared-agent sessions.
* Revoke tokens you no longer use:

```bash theme={null}
sitegpt tokens revoke <token-id>
```