Auth API
Signing in from the CLI, the signed-in user, and API tokens.
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 | |
label | "cli" | "web" | no (default "cli") |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
user | object | yes |
POST /v1/auth/cli/start
Anonymous; begins CLI sign-in; 429 past 10 pending per IP (or 500 overall)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
label | string | 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
Clerk session only; what's being approved, and where from
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) |
POST /v1/auth/cli/decide
Clerk session only (API tokens: 403); approve or deny
Body
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
approve | boolean | yes |
Response: 204, no body
POST /v1/auth/cli/poll
Anonymous; 202 pending, 403 denied, 410 expired
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 []) |
DELETE /v1/me
Deletes your account: workspaces only you are in (with their rooms and data), your tokens and sign-ins; shared workspaces you own pass to the earliest other member; your chat messages show as "Deleted user"
Response: 204, no body
POST /v1/me/blocks
Idempotent; 400 yourself, 404 unknown user; their room 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
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/tokens
Your CLI tokens (no hashes); current = this request's token
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
Response: 204, no body