Credential types
Send API tokens and the legacy API key in the
Authorization header:
API tokens
API tokens authenticate API v2 requests. Treat each token as an opaque secret. Do not check for a fixed token format in your code. API access is available on the Growth plan and above. This applies to API tokens, CLI logins, MCP, and the SDKs. Your own plan counts, and so does the plan of the account that owns the chatbot. See Which plan applies. The SiteGPT iPhone app is not affected.Which plan applies
A token belongs to the person who created it. The plan belongs to the chatbot. A request about a chatbot works when your own plan or the chatbot owner’s plan is Growth or above. See Plans and limits.
Your dashboard role and the token’s scopes still limit what you can do on each chatbot. The plan decides only if API access is included. When your role does not allow a request, it fails with
403 ROLE_PERMISSION_REQUIRED and a message that says what your role cannot do, in the words of the dashboard, and who can change your role. For example: “Your role on this chatbot cannot start conversations. The chatbot owner or an admin can change your role.” When only Super Admins can do it, for example for a chatbot transfer, the message ends with “Only a Super Admin can. The chatbot owner or another Super Admin can change your role.” When no team role can do it, it ends with “Only the SiteGPT team can do this.” error.details has the resource and the action. The Agent role cannot start conversations, so an Agent’s token with conversations:write gets this error on POST /api/v2/chatbots/{chatbotId}/messages and POST /api/v2/chatbots/{chatbotId}/conversations, which start a conversation. Messages in an existing conversation, replies from your team, and other updates to a conversation, such as a take-over, work.
When only an owner’s plan covers you:
GET /api/v2/chatbots,sitegpt chatbots list, and the MCP tools list only the chatbots that an owner’s plan covers.- A request about another chatbot that you can access fails with
403 PLAN_UPGRADE_REQUIREDand the message “API access to this chatbot needs its owner’s plan to be Growth or above. Ask the chatbot’s owner to upgrade, or upgrade your own plan.”error.details.chatbotIdnames the chatbot. A chatbot that you cannot access still returns404 CHATBOT_NOT_FOUND. - You cannot create a chatbot through the API or the CLI. A new chatbot belongs to your own account, so it needs your own plan. The request fails with
403 PLAN_UPGRADE_REQUIREDand the message “A new chatbot belongs to your own account, so creating one with an API token, the CLI or MCP needs your own plan to be Growth or above.” - You cannot list, accept, or decline chatbot transfers addressed to you through the API. A transferred chatbot moves to your own account. The request fails with
403 PLAN_UPGRADE_REQUIREDand the message “A transferred chatbot moves to your own account, so listing or answering transfers through the API needs your own plan to be Growth or above. You can accept or decline transfers on the dashboard on any plan.” - You can create and rotate tokens. When you create a token with Specific chatbots, it can include only chatbots that an owner’s plan covers. Otherwise SiteGPT refuses the token with the message about the chatbot’s owner. Rotating keeps the token’s chatbots. If no plan covers one of them anymore, rotating fails with
403 PLAN_UPGRADE_REQUIREDand the message about the chatbot’s owner, and the token keeps its current value. On the Agents page and the device login page, Specific chatbots lists only the chatbots that a plan covers. A token for All accessible chatbots works on the covered chatbots only. - If an owner downgrades below Growth, your requests about that owner’s chatbots fail with the plan error. If no chatbot is covered after that, all your requests fail.
Create a token
- In the top navigation, select Agents.
- In Create API token, enter a Token name. Name it after the tool that uses it.
- Choose when the token Expires: 30, 90, 180, or 365 days. The default is 90 days.
- Choose an Access level. See Access levels.
- Under Chatbot access, choose All accessible chatbots or Specific chatbots.
- Select Create token.
- Copy the token and store it in a safe place. SiteGPT shows it only once. Then select I saved this token.
Access levels
A token never gets more access than you have. SiteGPT gives only the scopes that your dashboard role allows on the chatbots you select. If your role does not allow some permissions, the Agents page tells you.
- Billing scopes need an account owner.
chatbots:writefor all chatbots needs an account owner.
Chatbot access
Use Specific chatbots for tools that work on one chatbot.
Manage tokens
The API Tokens list on the Agents page shows each token, its source, its scopes, and its status. The source is Manual token, Device login, or Onboarding token.- Rotate creates a new token value with the same settings. The old value stops working.
- Revoke stops the token at once.
- Select Show revoked to see revoked tokens. This option shows only when you have revoked tokens.
GET and POST /api/v2/tokens, DELETE /api/v2/tokens/{tokenId}, and POST /api/v2/tokens/{tokenId}/rotate. These need the tokens:read and tokens:write scopes.
Scopes
A scope allows one kind of action on one area.read lets the token view data. write lets it create and change data. delete lets it delete data.
Creating, renaming, and deleting a tag needs
conversations:write. conversations:delete does not cover tags.
Each API v2 operation lists the scopes it needs in the API reference. A request with a token that lacks a needed scope fails with 403 and the code TOKEN_SCOPE_NOT_ALLOWED.
OAuth device login
Device login lets a CLI, script, or local AI agent get an API token after you approve it in the browser. You do not paste a token into the tool.sitegpt login uses this flow. See Install and log in.
Use the endpoints below only if you build your own tool. Otherwise use sitegpt login.
How it works
- The tool sends a request to
POST https://sitegpt.ai/oauth/device_authorization. - SiteGPT returns a device code, a login code, and a link.
- You open the link and sign in. The Approve device login page shows the tool name and the access it asks for.
- You can narrow the access. Under Grant, choose Everything requested, Read only (shown when the request includes read scopes), or Choose specific. Then choose All chatbots or Specific chatbots.
- Under Token lifetime, keep the default As requested, or choose a shorter lifetime. Then select Approve or Deny.
- The tool polls
POST https://sitegpt.ai/oauth/tokenuntil you approve. It then gets an API token.
Token lifetime
The tool asks for a token lifetime in days. The CLI asks for 90 days by default. A tool can ask for up to 365 days. On the approval page, Token lifetime shows these choices:- As requested, with the requested number of days, for example As requested (90d). This is the default.
- 90 days, 30 days, and 7 days. Only the choices that are shorter than the request show.
Start the request
Send a form-encoded request:
Response:
verification_uri_complete in a browser. The device code expires after 15 minutes.
Poll for the token
Wait at least
interval seconds (2 seconds) between polls. After approval, the response has the token:
access_token as a bearer token for API v2.
Device login errors
Errors come back as{ "error": "...", "error_description": "..." }.
Discovery
Tools can find the device login endpoints in the OAuth metadata:Legacy API key
The legacy API key works with the legacy API v0 and v1 and with widget identity verification. It does not work with API v2, except forGET /api/v2/me, which returns a warning. For new work, use an API token.
- Plan: Growth plan and above. See Plans and limits.
- Where to find it: Open the Billing page. The key shows in the line “Your API Key is …”. It shows only when your plan includes API access.
- Creation: SiteGPT creates the key for you when your plan includes API access. The key does not change on its own. You cannot create or rotate it yourself.
- Access: The key acts as your user in the legacy API. It has no scopes, and you cannot limit it to some chatbots. On a chatbot where you are a team member, your role decides what the key can read and change, as in the dashboard. See Team members. A request that your role does not allow fails with status
403and a code for the action, for exampleCHATBOT_GENERAL_SETTINGS_UPDATE_FORBIDDEN.
Security
- Store tokens and keys in environment variables or a secret manager. Do not put them in source code, chat prompts, or logs.
- Give each tool its own token, with the smallest access that works.
- Use Specific chatbots for tools that work on one chatbot.
- Revoke tokens after a demo or when someone leaves your team.
- Never use the legacy API key in browser code.
Errors
A
401 response from API v2 includes a WWW-Authenticate header that points to the OAuth metadata. For all API v2 error codes, see API conventions.