Skip to content

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.

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.

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.

A cwt_ token carries one or more scopes. Each scope grants a specific class of action:

ScopeGrants
project:readList projects you can access
database:readList/inspect project databases, restore points, and restore operation status
database:writeCreate/delete project databases, rotate durable tokens, execute arbitrary SQL, start restores, and manage restore aliases
database:connectConnect to the SQL data plane; human cwt_ also requires owner/admin/member role
app:readList/inspect apps, builds, runtime logs, env, and app hostnames
app:writeCreate/delete apps, set env, attach/finalize/remove app hostnames
app:deployDeploy builds, roll back
domain:readList/inspect project domains and DNS records
domain:writeOnboard domains, manage DNS records
domain:purchaseRegistrar purchase
storage:readList Storage resources and read/list/head objects
storage:writeCreate/configure/delete Storage and mutate objects, including multipart uploads
repository:readCloud list/detail and Git clone/fetch/pull
repository:writeCloud create/delete and Git push; Git includes read, human viewers cannot write

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.

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.

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.

You can obtain a cwt_ token two ways: through CLI device login (recommended) or by creating a personal access token in the console.

Section titled “Option A — CLI device login (recommended)”

If you have the comwit CLI installed, run:

Terminal window
comwit login

This starts the device flow:

  1. The CLI calls POST /v1/auth/device and receives a user_code and a verification_uri.
  2. The CLI opens your browser to that URL. While signed in to the console, you approve the displayed code.
  3. The CLI polls POST /v1/auth/device/token until it receives your cwt_ token.

The token is saved to ~/.config/comwit/config.json. To pin a default project at the same time:

Terminal window
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:

Terminal window
comwit login --token cwt_xxx --project <projectId>

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 the COMWIT_CONFIG environment variable; otherwise it falls back to $XDG_CONFIG_HOME/comwit/config.json.
  • Project — the --project flag wins, then the COMWIT_PROJECT environment variable, then default_project from 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.

The CLI is convenient, but you can call the API directly with any HTTP client. Send your cwt_ token in the Authorization header:

List your projects
curl -H "Authorization: Bearer cwt_xxx" \
https://api.cloud.comwit.io/v1/projects

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

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.