Auth API
Signing in from the CLI and the browser, the signed-in user, API tokens, and everywhere you're signed in.
All paths are relative to the API origin. Send Authorization: Bearer <token> unless a route says otherwise; see the API overview for tokens and errors.
POST /v1/auth/dev-login
TESTS ONLY: 404 unless DEV_AUTH=true (never in production)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
handle | string | yes | |
name | string | no | |
email | string (email) | no | |
label | "cli" | "web" | no (default "cli") |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
user | object | yes |
POST /v1/auth/embed-token
Website sign-in only; a one-hour token for the comment panel on published pages, good only for GET /v1/me, GET /v1/spaces/:id, GET/POST /v1/spaces/:id/comments, POST /v1/spaces/:id/comment-images, GET /v1/spaces/:id/mention-people and PUT/DELETE /v1/comments/:id/reactions/:emoji
Response
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
expiresAt | number | yes |
POST /v1/auth/visitor-link
Website sign-in only; a two-minute ticket for the published-pages address (/_ct/link), which ties that browser's visitor cookie to you (your views of published pages show your name)
Response
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
expiresAt | number | yes |
POST /v1/auth/carry
Website sign-in only; keeps this browser's sign-ins for two minutes under a one-use ticket, so a move to our new web address keeps you signed in
Body
| Field | Type | Required | Notes |
|---|---|---|---|
state | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
ticket | string | yes | |
expiresAt | number | yes |
POST /v1/auth/carry/redeem
Anonymous; swaps a carry ticket for the sign-ins it holds, once; 404 bad, used or expired ticket
Body
| Field | Type | Required | Notes |
|---|---|---|---|
ticket | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
state | string | yes |
POST /v1/sessions
The bearer is a Clerk session token (401 otherwise); swaps it for a browser sign-in (returned once; ends 30 days after last use; not counted toward the device limit) and ends the Clerk session; announced like any new sign-in; 409 when that Clerk session was already swapped (a session becomes one sign-in). token: this browser's sign-in for the same account, kept and marked as just confirmed instead
Body
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
expiresAt | number | yes | |
user | object | yes |
GET /v1/auth/review-sign-in
Anonymous; 204 while App Review's sign-in is on, 404 otherwise
Response: 204, no body
POST /v1/auth/review-sign-in
Anonymous; App Review's sign-in for the Cloudy app: only the accounts REVIEW_SIGN_IN_USERS names, with the REVIEW_SIGN_IN_CODE secret (404 when either isn't set); makes the account on first use; the token is an app sign-in; 401 wrong username or code; 429 past 10 tries a minute
Body
| Field | Type | Required | Notes |
|---|---|---|---|
username | string | yes | |
code | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
user | object | yes |
POST /v1/auth/cli/start
Anonymous; begins a device sign-in (CLI, app or MCP); kind "mcp" only from apps/mcp (else 403); 429 past 10 pending per IP (or 500 overall)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
label | string | no | |
kind | "cli" | "app" | "mcp" | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
deviceCode | string | yes | |
userCode | string | yes | |
verificationUrl | string | yes | |
expiresIn | integer | yes | |
interval | integer | yes |
GET /v1/auth/cli/requests/:userCode
Website only (a Clerk session or a browser sign-in); what's being approved, where from, and its kind; 404 sign_in_unknown; 429 past 30 lookups a minute per user
Response
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
label | string | null | yes | |
createdAt | number | yes | |
expiresAt | number | yes | |
status | "pending" | "approved" | "denied" | "expired" | yes | |
requestedFrom | object | null | yes (default null) | |
userAgent | string | null | yes (default null) | |
kind | "cli" | "app" | "mcp" | null | yes (default null) | |
approverCountry | string | null | yes (default null) | |
limit | object | null | yes (default null) |
POST /v1/auth/cli/decide
Website only (device tokens: 403); approve or deny; 410 sign_in_expired, 404 sign_in_unknown, 429 as above; 409 sign_in_limit when approving would go past 5 devices (terminals and the app) or 10 AI apps
Body
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
approve | boolean | yes |
Response: 204, no body
POST /v1/auth/cli/poll
Anonymous; 202 pending, 403 sign_in_denied, 410 sign_in_expired (gone once collected), 404 sign_in_unknown
Body
| Field | Type | Required | Notes |
|---|---|---|---|
deviceCode | string | yes |
Response
Type: object
GET /v1/me
Response
| Field | Type | Required | Notes |
|---|---|---|---|
user | object | yes | |
workspaces | object[] | yes | |
invites | object[] | yes (default []) | |
preferences | object | yes (default \{"developerMode":false\}) | |
blocked | string[] | yes (default []) | |
deletion | object | null | yes (default null) |
DELETE /v1/me
From the website or the Cloudy app only (CLI and MCP tokens: 403); asks for your account to be deleted in 7 days (GET /v1/me deletion.at), with an email to cancel; then workspaces only you are in (with their live spaces and data), your tokens and sign-ins go; shared workspaces you own pass to the earliest other member; your chat messages show as "Deleted user"
Response: 204, no body
POST /v1/me/deletion/cancel
Cancels a pending deletion (any sign-in)
Response: 204, no body
POST /v1/auth/cancel-deletion
Anonymous; the deletion email's link: cancels it; 404 bad or expired link
Body
| Field | Type | Required | Notes |
|---|---|---|---|
ticket | string | yes |
Response: 204, no body
POST /v1/me/blocks
Idempotent; 400 yourself, 404 unknown user; their live space chat stops reaching you from your next connect
Body
| Field | Type | Required | Notes |
|---|---|---|---|
userId | string | yes |
Response: 204, no body
DELETE /v1/me/blocks/:userId
Idempotent
Response: 204, no body
POST /v1/me/push-devices
Idempotent; this phone gets push notifications for you, as well as for other accounts signed in on it (each alert then starts with "@handle · "; every push's data has the account's userId); ending the sign-in that registered it stops them
Body
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
environment | "sandbox" | "production" | yes |
Response: 204, no body
DELETE /v1/me/push-devices/:token
Idempotent; on signing out of this account: the phone's other accounts keep theirs
Response: 204, no body
GET /v1/me/notifications
Push on or off, quiet hours, your time zone, and the spaces you muted
Response
| Field | Type | Required | Notes |
|---|---|---|---|
push | boolean | yes | |
devices | number | yes | |
quietHours | object | null | yes | |
timeZone | string | null | yes | |
muted | object[] | yes | |
workspaces | object[] | yes |
PATCH /v1/me/notifications
400 unknown time zone or a workspace you're not in; workspaces sets each one's level (all, participating, none)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
push | boolean | no | |
quietHours | object | null | no | |
timeZone | string | no | |
workspaces | object | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
push | boolean | yes | |
devices | number | yes | |
quietHours | object | null | yes | |
timeZone | string | null | yes | |
muted | object[] | yes | |
workspaces | object[] | yes |
GET /v1/me/space-reads
?spaces=a,b (at most 50): when you last read each one's comments, anywhere
Query
| Field | Type | Required | Notes |
|---|---|---|---|
spaces | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
reads | object | yes |
PATCH /v1/me/preferences
Your own view settings (developer mode)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
developerMode | boolean | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
developerMode | boolean | yes |
GET /v1/me/email-preferences
Which optional emails you get (invitations, comments, product news); account and billing emails are always sent
Response
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | null | yes | |
categories | object[] | yes |
PATCH /v1/me/email-preferences
Turn categories on or off; product news is off until you turn it on
Body
| Field | Type | Required | Notes |
|---|---|---|---|
invites | boolean | no | |
activity | boolean | no | |
product | boolean | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | null | yes | |
categories | object[] | yes |
GET /v1/me/at-link
The public space cloudy.page/@handle serves (null: /@handle 301s to /u/handle), and the spaces you may pick
Response
| Field | Type | Required | Notes |
|---|---|---|---|
spaceId | string | null | yes | |
choices | object[] | yes | |
searchIndexed | boolean | no |
PUT /v1/me/at-link
A person only (website or app); spaceId one of choices, or null; 400 otherwise; searchIndexed: show your profile in search engines
Body
| Field | Type | Required | Notes |
|---|---|---|---|
spaceId | string | null | no | |
searchIndexed | boolean | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
spaceId | string | null | yes | |
choices | object[] | yes | |
searchIndexed | boolean | no |
PATCH /v1/me/handle
400 reserved, 409 taken; your personal workspace's slug (and name, if unchanged) follow when it matched the old handle and the new one is free
Body
| Field | Type | Required | Notes |
|---|---|---|---|
handle | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
handle | string | yes | |
name | string | null | yes | |
avatarUrl | string | null | no |
PUT /v1/me/avatar
Your profile picture: WebP or JPEG by magic bytes, exactly 256 x 256, 256 KB, still, no EXIF/XMP; 20 changes a day (429); the old one is deleted
Request: raw image bytes
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
handle | string | yes | |
name | string | null | yes | |
avatarUrl | string | null | no |
DELETE /v1/me/avatar
Back to initials; counts toward the 20 a day
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
handle | string | yes | |
name | string | null | yes | |
avatarUrl | string | null | no |
GET /v1/tokens
Your device sign-ins: CLI, app and MCP (no hashes); current = this request's token; kind = which client
Response
| Field | Type | Required | Notes |
|---|---|---|---|
tokens | object[] | yes |
DELETE /v1/tokens/current
Revokes the token making the request (400 with a Clerk session)
Response: 204, no body
DELETE /v1/tokens/:id
Revokes one of your own tokens; 404 otherwise; any but the caller's own: website or app only (CLI and MCP tokens: 403)
Response: 204, no body
GET /v1/sign-ins
Every place you're signed in: browsers, CLI, app and MCP; current first; isNew = under a day old
Response
| Field | Type | Required | Notes |
|---|---|---|---|
signIns | object[] | yes | |
settledAt | number | yes | |
idleDays | integer | yes |
DELETE /v1/sign-ins/:id
Signs one out (yours only, 404 otherwise); another than the caller: website or app only, and 403 sign_in_too_new from a sign-in under a day old unless that one is unused for 30 days
Response: 204, no body
POST /v1/sign-ins/sign-out-others
Signs out every other sign-in; website or app only; 403 sign_in_too_new from a sign-in under a day old
Response
| Field | Type | Required | Notes |
|---|---|---|---|
signedOut | integer | yes |
POST /v1/auth/not-me/preview
Anonymous; the sign-in a new sign-in email's "This wasn't me" link is about (null once ended); 404 bad or expired link
Body
| Field | Type | Required | Notes |
|---|---|---|---|
ticket | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
signIn | object | null | yes |
POST /v1/auth/not-me
Anonymous; ends that one sign-in; 404 bad or expired link
Body
| Field | Type | Required | Notes |
|---|---|---|---|
ticket | string | yes |
Response: 204, no body
PUT /v1/me/favorites
Your favorites in this order (others after, as they were)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
spaces | string[] | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
spaces | string[] | yes |