Skip to content
Cloudy docs

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

FieldTypeRequiredNotes
handlestringyes
namestringno
emailstring (email)no
label"cli" | "web"no (default "cli")

Response

FieldTypeRequiredNotes
tokenstringyes
userobjectyes

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

FieldTypeRequiredNotes
tokenstringyes
expiresAtnumberyes

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

FieldTypeRequiredNotes
tokenstringyes
expiresAtnumberyes

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

FieldTypeRequiredNotes
statestringyes

Response

FieldTypeRequiredNotes
ticketstringyes
expiresAtnumberyes

POST /v1/auth/carry/redeem

Anonymous; swaps a carry ticket for the sign-ins it holds, once; 404 bad, used or expired ticket

Body

FieldTypeRequiredNotes
ticketstringyes

Response

FieldTypeRequiredNotes
statestringyes

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

FieldTypeRequiredNotes
tokenstringno

Response

FieldTypeRequiredNotes
tokenstringyes
expiresAtnumberyes
userobjectyes

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

FieldTypeRequiredNotes
usernamestringyes
codestringyes

Response

FieldTypeRequiredNotes
tokenstringyes
userobjectyes

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

FieldTypeRequiredNotes
labelstringno
kind"cli" | "app" | "mcp"no

Response

FieldTypeRequiredNotes
deviceCodestringyes
userCodestringyes
verificationUrlstringyes
expiresInintegeryes
intervalintegeryes

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

FieldTypeRequiredNotes
userCodestringyes
labelstring | nullyes
createdAtnumberyes
expiresAtnumberyes
status"pending" | "approved" | "denied" | "expired"yes
requestedFromobject | nullyes (default null)
userAgentstring | nullyes (default null)
kind"cli" | "app" | "mcp" | nullyes (default null)
approverCountrystring | nullyes (default null)
limitobject | nullyes (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

FieldTypeRequiredNotes
userCodestringyes
approvebooleanyes

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

FieldTypeRequiredNotes
deviceCodestringyes

Response

Type: object

GET /v1/me

Response

FieldTypeRequiredNotes
userobjectyes
workspacesobject[]yes
invitesobject[]yes (default [])
preferencesobjectyes (default \{"developerMode":false\})
blockedstring[]yes (default [])
deletionobject | nullyes (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

FieldTypeRequiredNotes
ticketstringyes

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

FieldTypeRequiredNotes
userIdstringyes

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

FieldTypeRequiredNotes
tokenstringyes
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

FieldTypeRequiredNotes
pushbooleanyes
devicesnumberyes
quietHoursobject | nullyes
timeZonestring | nullyes
mutedobject[]yes
workspacesobject[]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

FieldTypeRequiredNotes
pushbooleanno
quietHoursobject | nullno
timeZonestringno
workspacesobjectno

Response

FieldTypeRequiredNotes
pushbooleanyes
devicesnumberyes
quietHoursobject | nullyes
timeZonestring | nullyes
mutedobject[]yes
workspacesobject[]yes

GET /v1/me/space-reads

?spaces=a,b (at most 50): when you last read each one's comments, anywhere

Query

FieldTypeRequiredNotes
spacesstringyes

Response

FieldTypeRequiredNotes
readsobjectyes

PATCH /v1/me/preferences

Your own view settings (developer mode)

Body

FieldTypeRequiredNotes
developerModebooleanno

Response

FieldTypeRequiredNotes
developerModebooleanyes

GET /v1/me/email-preferences

Which optional emails you get (invitations, comments, product news); account and billing emails are always sent

Response

FieldTypeRequiredNotes
emailstring | nullyes
categoriesobject[]yes

PATCH /v1/me/email-preferences

Turn categories on or off; product news is off until you turn it on

Body

FieldTypeRequiredNotes
invitesbooleanno
activitybooleanno
productbooleanno

Response

FieldTypeRequiredNotes
emailstring | nullyes
categoriesobject[]yes

The public space cloudy.page/@handle serves (null: /@handle 301s to /u/handle), and the spaces you may pick

Response

FieldTypeRequiredNotes
spaceIdstring | nullyes
choicesobject[]yes
searchIndexedbooleanno

A person only (website or app); spaceId one of choices, or null; 400 otherwise; searchIndexed: show your profile in search engines

Body

FieldTypeRequiredNotes
spaceIdstring | nullno
searchIndexedbooleanno

Response

FieldTypeRequiredNotes
spaceIdstring | nullyes
choicesobject[]yes
searchIndexedbooleanno

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

FieldTypeRequiredNotes
handlestringyes

Response

FieldTypeRequiredNotes
idstringyes
handlestringyes
namestring | nullyes
avatarUrlstring | nullno

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

FieldTypeRequiredNotes
idstringyes
handlestringyes
namestring | nullyes
avatarUrlstring | nullno

DELETE /v1/me/avatar

Back to initials; counts toward the 20 a day

Response

FieldTypeRequiredNotes
idstringyes
handlestringyes
namestring | nullyes
avatarUrlstring | nullno

GET /v1/tokens

Your device sign-ins: CLI, app and MCP (no hashes); current = this request's token; kind = which client

Response

FieldTypeRequiredNotes
tokensobject[]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

FieldTypeRequiredNotes
signInsobject[]yes
settledAtnumberyes
idleDaysintegeryes

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

FieldTypeRequiredNotes
signedOutintegeryes

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

FieldTypeRequiredNotes
ticketstringyes

Response

FieldTypeRequiredNotes
signInobject | nullyes

POST /v1/auth/not-me

Anonymous; ends that one sign-in; 404 bad or expired link

Body

FieldTypeRequiredNotes
ticketstringyes

Response: 204, no body

PUT /v1/me/favorites

Your favorites in this order (others after, as they were)

Body

FieldTypeRequiredNotes
spacesstring[]yes

Response

FieldTypeRequiredNotes
spacesstring[]yes