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

​
Authentication methods

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.

​
Manual dashboard-token login

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

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

Copy the token

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

Save it in the CLI

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

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 levelHow to requestBest for
Standard CLI accesssitegpt loginMost day-to-day CLI usage without token, billing, or integration writes.
Full account accesssitegpt login --full-accessTrusted local workflows that need broad SiteGPT management.
Custom accesssitegpt login --scope <scope>Specialized agents and automation with least-privilege tokens.
Chatbot-restricted accesssitegpt 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

ResourceReadWriteDelete
Accountaccount:readaccount:write-
Billingbilling:readbilling:write-
API tokenstokens:readtokens:write-
Chatbotschatbots:readchatbots:writechatbots:delete
Knowledgeknowledge:readknowledge:writeknowledge:delete
Personaspersonas:readpersonas:writepersonas:delete
Instructionsinstructions:readinstructions:writeinstructions:delete
Settingssettings:readsettings:write-
Conversation startersstarters:readstarters:writestarters:delete
Conversation followupsfollowups:readfollowups:writefollowups:delete
Conversationsconversations:readconversations:writeconversations:delete
Leadsleads:readleads:writeleads:delete
Membersmembers:readmembers:writemembers:delete
Integrationsintegrations:readintegrations: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

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