Skip to main content

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.

SiteGPT supports OAuth Device Authorization Grant for local CLIs, scripts, and personal AI agents. This is the protocol used by sitegpt login. Use this page when you are building an agent or integration that wants to authenticate without asking the user to copy a token manually.
Most users should run sitegpt login instead of calling these endpoints directly. The CLI handles device authorization, polling, profile storage, and API token use.

​
Discovery

Agents can discover SiteGPT’s OAuth device flow from the authorization-server metadata: 
curl https://sitegpt.ai/.well-known/oauth-authorization-server
The protected API resource metadata is available at: 
curl https://sitegpt.ai/.well-known/oauth-protected-resource
curl https://sitegpt.ai/.well-known/oauth-protected-resource/api/v2
The API resource is: 
https://sitegpt.ai/api/v2

​
Client ID

Use this client ID for the first-party SiteGPT CLI/device flow: 
sitegpt-cli
client_id identifies the application requesting access. It is not a secret and does not identify the user. All users of the SiteGPT CLI use the same client_id.

​
Start device authorization

Send a form-encoded request to /oauth/device_authorization: 
curl -s -X POST https://sitegpt.ai/oauth/device_authorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=sitegpt-cli" \
  -d "token_name=SiteGPT CLI" \
  -d "scope=account:read chatbots:read knowledge:write"
Response: 
{
  "device_code": "sgpt_device_...",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://sitegpt.ai/device",
  "verification_uri_complete": "https://sitegpt.ai/device?user_code=ABCD-EFGH",
  "expires_in": 899,
  "interval": 2
}
Open verification_uri_complete in a browser. The signed-in SiteGPT user reviews the requested access and approves or denies the request.

​
Poll for the token

Poll /oauth/token with the device code: 
curl -s -X POST https://sitegpt.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "client_id=sitegpt-cli" \
  -d "device_code=<device_code>"
Before approval, SiteGPT returns: 
{
  "error": "authorization_pending",
  "error_description": "Device login is pending approval.",
  "interval": 2
}
Respect the interval before polling again. If you poll too quickly, SiteGPT can return: 
{
  "error": "slow_down",
  "error_description": "Poll interval is too short. Wait before polling again.",
  "interval": 7
}
After approval, SiteGPT returns a scoped bearer token: 
{
  "access_token": "sgpt_...",
  "token_type": "Bearer",
  "expires_in": 7775999,
  "scope": "account:read chatbots:read knowledge:write",
  "sitegpt_token": {
    "id": "token-id",
    "name": "SiteGPT CLI",
    "tokenPrefix": "sgpt_...",
    "scopes": ["account:read", "chatbots:read", "knowledge:write"],
    "chatbotIds": [],
    "expiresAt": "2026-08-11T00:00:00.000Z"
  }
}
Use access_token as the bearer token for /api/v2 requests: 
curl https://sitegpt.ai/api/v2/me \
  -H "Authorization: Bearer sgpt_..."

​
Request fields

​
/oauth/device_authorization

FieldRequiredDescription
client_idYesUse sitegpt-cli for the first-party SiteGPT CLI/device flow.
scopeNoSpace-separated SiteGPT scopes. If omitted, SiteGPT requests standard CLI access. See available scopes.
full_accessNoDefault: false. Set to true to request all self-service scopes the approving user’s dashboard role can issue. Do not send this with scope.
token_nameNoToken name shown in the dashboard.
nameNoAlias for token_name.
expires_in_daysNoToken lifetime in days. Valid range: 1-365. Default: 90.
chatbot_idNoRestrict access to one chatbot. Repeat for multiple chatbots.
chatbot_idsNoComma-separated chatbot IDs.

​
/oauth/token

FieldRequiredDescription
grant_typeYesMust be urn:ietf:params:oauth:grant-type:device_code.
client_idYesUse the same client ID used to start authorization. For the SiteGPT CLI, use sitegpt-cli.
device_codeYesThe device_code returned by /oauth/device_authorization.

​
Error responses

ErrorMeaning
authorization_pendingThe user has not approved the browser prompt yet. Wait and poll again.
slow_downThe client is polling too quickly. Increase the polling interval.
access_deniedThe user denied the request. Stop polling.
expired_tokenThe device code expired. Start a new login.
invalid_grantThe device code is invalid, consumed, or no longer usable.
invalid_scopeOne or more requested scopes are not valid or not self-service.
invalid_requestRequired fields are missing or malformed.

​
Security notes

  • Do not put access_token in prompts, shared chats, source code, or logs.
  • Use the smallest scope set needed for the agent.
  • Use chatbot_id restrictions for chatbot-specific agents.
  • Rotate or revoke tokens after demos and shared sessions.
  • For normal CLI usage, prefer sitegpt login; it stores the token in a local profile.