Authentication & scopes
Every request to the Comwit Cloud API at https://api.cloud.comwit.io is
authenticated with a bearer token sent in the Authorization header:
Authorization: Bearer <token>If you have never used the API before, the short version is: you get a personal
access token (it starts with cwt_), and you send it on every call. This page
explains the two kinds of tokens, what scopes are, and how to obtain your token
with the comwit CLI or the console.
Token classes
Section titled “Token classes”There are three token classes. Developers use cwt_ locally and cwp_ in a
deployed service; the internal server token is not a public credential.
cwt_<hex> — user personal access token (what you use)
Section titled “cwt_<hex> — user personal access token (what you use)”A personal access token (PAT) is tied to your user account. It starts with
the prefix cwt_ followed by a hex string. A cwt_ token is scoped: it can
only perform the actions its scopes allow, and it can only touch projects you
are a member of.
On every request, the API verifies the token and enforces both scope and project membership. If the token lacks the required scope, or you are not a member of the target project, the request is rejected.
cwp_<hex> — project machine token
Section titled “cwp_<hex> — project machine token”A project token belongs to exactly one project rather than one person. Use it
for deployed apps and CI that must survive a team member leaving. Its allowed
surface is intentionally smaller than a user token. It may carry app:read,
app:deploy, database:connect, storage:read, and storage:write, plus explicit
repository:read / repository:write for Git access and mcp for the Comwit
MCP server, without
granting database lifecycle or domain administration. Create and revoke these
tokens under Project → Settings → Project tokens.
mcp is project-token-only and grants no Cloud API authority. Local Comwit MCP
uses an active cwt_; sandbox MCP uses an active cwp_. Comwit may require
mcp for sandbox project tokens; that decision is pending. User tokens never
carry mcp. In Custom, select Comwit MCP → Use Comwit MCP;
project Full access includes it. Existing tokens keep their issued scopes;
issue a replacement with mcp when MCP access is needed. Personal token
scopes and defaults are unchanged.
Comwit’s server checks both token classes with POST /internal/token/introspect,
live since v0.13.0. It sends its existing COMWIT_PROVISION_SECRET in exactly
one Authorization: Bearer <COMWIT_PROVISION_SECRET> header, the same key and
header used for /internal/provision/*. The route is absent (404) without
that secret or the console DB client. Keep this service credential server-side;
client-token users do not need it.
An active response identifies principal_type as user or project. For a
project token, Comwit compares project_id with its target. For a user token,
it finds the target in projects, which lists project_id, organization_id,
and the effective role (owner, admin, member, or viewer). Organization
roles take precedence over direct project roles. A project-scoped user token
returns only that project. A user with no memberships still has an active
token and projects: [], so Comwit denies project access. More than 512
projects returns 503 without a partial list. Both token classes return only
their granted known scopes and may include expiry (exp) and issuance time
(iat); non-expiring tokens omit exp.
PLATFORM_API_SERVER_TOKEN — internal operator/web token (not for you)
Section titled “PLATFORM_API_SERVER_TOKEN — internal operator/web token (not for you)”PLATFORM_API_SERVER_TOKEN is a shared, global-access token used internally by
the Comwit Cloud console and by operators. It bypasses scope and
membership checks, so it is powerful and is not issued to CLI or API end
users.
When the console makes a change on a user’s behalf using this internal token, it
adds an X-Comwit-Actor-User-Id header so that audit logs and console writes are
attributed to the real user. Direct cwt_ callers never send that header — the
API uses the user id from the introspected token itself.
Scopes
Section titled “Scopes”A cwt_ token carries one or more scopes. Each scope grants a specific class of
action:
| Scope | Grants |
|---|---|
project:read | List projects you can access |
database:read | List/inspect project databases, restore points, and restore operation status |
database:write | Create/delete project databases, rotate durable tokens, execute arbitrary SQL, start restores, and manage restore aliases |
database:connect | Connect to the SQL data plane; human cwt_ also requires owner/admin/member role |
app:read | List/inspect apps, builds, runtime logs, env, and app hostnames |
app:write | Create/delete apps, set env, attach/finalize/remove app hostnames |
app:deploy | Deploy builds, roll back |
domain:read | List/inspect project domains and DNS records |
domain:write | Onboard domains, manage DNS records |
domain:purchase | Registrar purchase |
storage:read | List Storage resources and read/list/head objects |
storage:write | Create/configure/delete Storage and mutate objects, including multipart uploads |
repository:read | Cloud list/detail and Git clone/fetch/pull |
repository:write | Cloud create/delete and Git push; Git includes read, human viewers cannot write |
Operator-only routes
Section titled “Operator-only routes”Some routes are reserved for operators and the console. A cwt_ or cwp_ token is
rejected with 403 on:
/v1/status- the non-project
/v1/databases*family - hidden legacy aliases
These routes require the internal operator token, not a public token.
The old POST /v1/databases create route is additionally retired: even an
operator request receives 410 Gone and must use the project-scoped create
route. The other flat database routes remain available for operator repair.
S3 client authentication
Section titled “S3 client authentication”For https://storage.cloud.comwit.io, put the same cwt_ or cwp_ value in
the S3 session-token field. The access-key and secret-key fields are non-secret
SDK placeholders. See Use the S3 API for the exact client
configuration. Never place a Comwit token in browser code.
Project-scoped database routes such as
/v1/projects/{projectId}/databases/{databaseId}/token/rotate, .../query, and
.../restore are normal user routes and authorize with the documented database
scope plus project membership. The query and PITR routes are live in
platform-api.
Git authentication
Section titled “Git authentication”A cwt_ or cwp_ token needs repository:read for Cloud list/detail;
repository:read grants Git clone/fetch/pull, and repository:write grants
Cloud create/delete and Git push (Git write permission includes read).
Human default tokens and CLI device login include both scopes; viewer-only
human tokens include read. Select scopes explicitly for a project cwp_ token.
Human owners, admins, and members may write; viewers may read. A project token
can act only within its owning project.
Ready repositories expose a clone URL at
https://git.cloud.comwit.io/<projectId>/<repositoryId>.git. Git HTTPS uses the
token as the Basic password with any username. The Git data API also accepts a
Bearer token. comwit login configures a credential helper for that host so Git
can use the saved token without a password prompt. Never put tokens in URLs or
logs. Create and delete through the Cloud API or console; see the
repository guide.
Getting a cwt_ token
Section titled “Getting a cwt_ token”You can obtain a cwt_ token two ways: through CLI device login (recommended)
or by creating a personal access token in the console.
Option A — CLI device login (recommended)
Section titled “Option A — CLI device login (recommended)”If you have the comwit CLI installed, run:
comwit loginThis starts the device flow:
- The CLI calls
POST /v1/auth/deviceand receives auser_codeand averification_uri. - The CLI opens your browser to that URL. While signed in to the console, you approve the displayed code.
- The CLI polls
POST /v1/auth/device/tokenuntil it receives yourcwt_token.
The token is saved to ~/.config/comwit/config.json. To pin a default project at
the same time:
comwit login --project <projectId>Option B — dashboard personal access token
Section titled “Option B — dashboard personal access token”You can also create a scoped cwt_ token directly in the console at /tokens
(account menu → API tokens → Create token, then a preset or Custom scopes).
Once you have it, hand it to the CLI:
comwit login --token cwt_xxx --project <projectId>CLI config and resolution order
Section titled “CLI config and resolution order”The CLI resolves your token, project, and API host in a fixed order. Knowing this order makes it easy to override settings per command or per environment.
- Token / config file — read from
~/.config/comwit/config.json, which holds{ "token", "default_project" }. Override the path with theCOMWIT_CONFIGenvironment variable; otherwise it falls back to$XDG_CONFIG_HOME/comwit/config.json. - Project — the
--projectflag wins, then theCOMWIT_PROJECTenvironment variable, thendefault_projectfrom the config file. - API host — defaults to
https://api.cloud.comwit.io.
comwit update is different: it talks to GitHub releases, not the Comwit
platform API. Private release downloads use GitHub credentials such as
COMWIT_UPDATE_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN, or gh auth token;
they do not use your cwt_ API token.
Using a token with raw HTTP
Section titled “Using a token with raw HTTP”The CLI is convenient, but you can call the API directly with any HTTP client.
Send your cwt_ token in the Authorization header:
curl -H "Authorization: Bearer cwt_xxx" \ https://api.cloud.comwit.io/v1/projectsEach listed project has project_id, name, organization_id, and role,
your effective membership role (owner, admin, member, or viewer). An
organization role takes precedence over a project role. Project tokens
(cwp_) cannot carry project:read, so this call returns 403 for them.
What rejection looks like
Section titled “What rejection looks like”A request that asks for an action outside your token’s scopes, or that targets a
project you are not a member of, is rejected with HTTP 403. The operator-only
routes listed above also return 403 for cwt_ tokens.
For the full error shape and how to retry safely, see Errors & idempotency.
Next steps
Section titled “Next steps”- API overview — base URL, versioning, and request basics.
- Install the CLI — get the
comwitbinary. - Errors & idempotency — status codes and retries.