CT Watch

How auth works

CT Watch hosts an OAuth 2.1 authorization server. There are no API keys and no shared secrets — every caller authenticates as a user, and tokens are short-lived and refreshable.

Two grant types, one identity

| Client | Grant | Used by | |---|---|---| | web | authorization code + PKCE | this website (browser) | | cli | device code (RFC 8628) | the ctw CLI |

Both resolve to the same account. Both are public clients — they hold no client secret; PKCE (browser) and the device-code exchange (CLI) prove possession instead.

Browser: authorization code + PKCE

  1. You click Sign in; the site generates a PKCE verifier and a state nonce, stores them in short-lived cookies, and redirects to CT Watch’s /authorize.
  2. CT Watch authenticates you on its own hosted pages (login, consent, MFA) — the site never sees your password.
  3. CT Watch redirects back to the site’s /callback with a one-time code; the site exchanges it (with the PKCE verifier) at CT Watch’s /token server-side.
  4. The resulting tokens are stored server-side; your browser gets only an opaque session cookie.

Two-factor is required. On your first sign-in you’re asked to set up a second factor (an authenticator app or a passkey) before you get a token — see Accounts & sign-in. A password on its own can never reach your account.

CLI: device code

  1. ctw login asks CT Watch for a device + user code and prints a verification URL.
  2. You open the URL in any browser and approve the code (signing in / MFA as needed).
  3. The CLI polls CT Watch’s /token until you approve, then stores the tokens locally at mode 0600.

This is why the CLI works on a headless box: the box never needs a browser, only the device you approve on.

Tokens & refresh

Access tokens are opaque and short-lived; a refresh token mints new ones. The browser session and the CLI both refresh automatically before expiry, so you stay signed in without re-authenticating. Signing out (browser Sign out or ctw logout) revokes/discards the tokens.

Scopes

Tokens carry scopes: read (search, list rules/targets/usage) and manage (create/delete rules and targets). The website and CLI request both, so a signed-in session can do everything the dashboard exposes.

What’s gone

There is no client_credentials grant and no HMAC/API-key auth — both were removed in favour of the flows above. The website holds no CT Watch secret at all; it is purely a public PKCE client.