Authentication and scopes

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

Authentication methods

OAuth device login
Existing token
Environment variable

Recommended for humans and local AI assistants:

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.

Useful for CI, servers, and environments where browser approval is not available:

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.

Useful for one-off scripts:

SITEGPT_API_TOKEN=<sitegpt-api-token> sitegpt chatbots list

Environment variables override the saved profile for that command.

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

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.

Copy the token

Copy the plaintext token immediately. SiteGPT stores only a secure hash and cannot show the same token again.

Save it in the CLI

sitegpt login --token <sitegpt-api-token>

Use a named profile when needed

sitegpt login --profile knowledge-agent --token <sitegpt-api-token>
sitegpt --profile knowledge-agent whoami

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:

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:

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:

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.

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.

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

For personal AI assistants, use a dedicated named profile and give the agent only the scopes it needs. See 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

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 and API token commands.

Token lifecycle

Newly created and rotated tokens are shown once:

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:

sitegpt login \
  --profile inventory \
  --scope account:read \
  --scope chatbots:read

Knowledge-only updater for one chatbot:

sitegpt login \
  --profile knowledge-bot \
  --chatbot <chatbot-id> \
  --scope account:read \
  --scope chatbots:read \
  --scope knowledge:read \
  --scope knowledge:write

Support queue agent:

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:

sitegpt tokens revoke <token-id>

Get started

Chatbot setup

Operations

Agent playbooks

Reference

Authentication and scopes

Authentication methods

OAuth device flow for agents

Access levels

Available scopes

Token commands

Create options

Token lifecycle

Least-privilege examples

Security notes

​Authentication methods

​Manual dashboard-token login

​OAuth device flow for agents

​Access levels

​Available scopes

​Token commands

​Create options

​Token lifecycle

​Least-privilege examples

​Security notes

Authentication methods

Manual dashboard-token login

OAuth device flow for agents

Access levels

Available scopes

Token commands

Create options

Token lifecycle

Least-privilege examples

Security notes