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

There are two classes of token. As a user, you only ever use the first one.

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.

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 (apps/web) and by operators. It bypasses scope and membership checks, so it is powerful and is not issued to CLI or API end users.

Caution

Never use PLATFORM_API_SERVER_TOKEN as a user token. User tokens are the scoped cwt_ PATs described above. The server token is internal-only.

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

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
database:write	Create databases
app:read	List/inspect apps, builds, env, domains
app:write	Create/delete apps, set env, attach 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

Planned

The domain:purchase scope (registrar purchase) is planned and not yet live. Do not depend on it for current workflows.

Tip

Grant only the scopes a token actually needs. A read-only automation, for example, is safer with just project:read and app:read than with write or deploy scopes.

Operator-only routes

Some routes are reserved for operators and the console. A cwt_ user 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 user PAT.

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)

If you have the comwit CLI installed, run:

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:

comwit login --project <projectId>

Note

New to the CLI? See Install the CLI to get the comwit binary first.

Option B — dashboard personal access token

You can also create a scoped cwt_ token directly in the console at /tokens. Once you have it, hand it to the CLI:

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

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

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:

List your projects

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

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

• API overview — base URL, versioning, and request basics.
• Install the CLI — get the comwit binary.
• Errors & idempotency — status codes and retries.