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

# API v2 authentication

> Authenticate to API v2 with scoped SiteGPT bearer tokens, dashboard-created tokens, or OAuth device login.

API v2 accepts SiteGPT API tokens as bearer credentials:

```bash theme={null}
Authorization: Bearer sgpt_xxxxxxxxx
```

Tokens are scoped. A token can only perform actions allowed by its scopes, chatbot restrictions, and the dashboard role of the user who created it.

## Dashboard-created tokens

Use this flow when a human wants to choose permissions in the SiteGPT dashboard.

<Steps>
  <Step title="Open Agents">
    In the SiteGPT dashboard, open **Agents**.
  </Step>

  <Step title="Create token">
    Click **Create token**, choose Standard, Full, or Custom access, and optionally restrict access to selected chatbots.
  </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="Use the token">
    Send it as a bearer token in API v2 requests.
  </Step>
</Steps>

## OAuth device login

Use this flow when a CLI, local tool, or personal AI agent needs browser-approved access without asking the user to paste a token into chat.

The first-party SiteGPT CLI uses:

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

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

OAuth endpoints:

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

The OAuth device flow returns an opaque SiteGPT access token that looks like `sgpt_xxxxxxxxx`. Use that token as the bearer credential for API v2.

For the complete request fields, polling behavior, error codes, and examples, see [OAuth device flow](/cli/oauth-device-flow).

## Scopes

Use the smallest scope set needed by your integration.

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

## Security notes

* Treat `sgpt_xxxxxxxxx` tokens as secrets.
* Prefer chatbot-restricted tokens for agents that only manage one chatbot.
* Rotate or revoke tokens after demos, shared sessions, or leaked logs.
* Do not hardcode tokens in source code.
* Do not validate one exact token prefix in your code. Treat SiteGPT tokens as opaque bearer credentials.