Device login (command line)
The routes behind qaldy login: a terminal asks for a code, a person approves it in the console. 5 routes, from the API’s own OpenAPI document.
5 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| POST | /v1/cli/device | Start a CLI sign-in: a device code to poll with and a user code to show (no sign-in) |
| GET | /v1/cli/device/{userCode} | What a waiting CLI sign-in asks for, and where you may approve it (console) |
| POST | /v1/cli/device/{userCode}/approve | Approve a CLI sign-in for one workspace, with at most the scopes it asked for (console) |
| POST | /v1/cli/device/{userCode}/deny | Refuse a CLI sign-in (console) |
| POST | /v1/cli/device/poll | Ask whether a CLI sign-in was approved; the token comes back once (no sign-in) |
Reference#
POST /v1/cli/device#
Start a CLI sign-in: a device code to poll with and a user code to show (no sign-in).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: public: a terminal has no sign-in yet; rate-limited, at most 2,000 logins open at once
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
client | string | yes | |
purpose | "login" · "token" | default "login" | |
name | string | 1 to 60 characters | |
scopes | "read" · "write"[] | up to 2 items. default read,write | |
expiresInDays | integer | 1 to 365. default 90 | |
host | string | 1 to 64 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
deviceCode | string | yes | |
userCode | string | yes | |
verificationUri | string (uri) | yes | |
verificationUriComplete | string (uri) | yes | |
expiresIn | integer | yes | at least 1 |
interval | integer | yes | at least 1 |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/cli/device/{userCode}#
What a waiting CLI sign-in asks for, and where you may approve it (console).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: signed in (a token gets
console_only)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
userCode | path | string | yes | 1 to 32 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
client | string | yes | at least 1 characters |
purpose | "login" · "token" | yes | |
name | string | yes | 1 to 60 characters |
scopes | "read" · "write"[] | yes | up to 2 items |
expiresInDays | integer | yes | 1 to 365 |
host | string or null | yes | |
status | "pending" · "approved" · "denied" · "expired" | yes | |
createdAt | string | yes | at least 1 characters |
expiresAt | string | yes | at least 1 characters |
workspaces | object[] | yes | |
workspaces[].id | string | yes | at least 1 characters |
workspaces[].name | string | yes | at least 1 characters |
workspaces[].slug | string | yes | at least 1 characters |
workspaces[].role | "owner" · "admin" · "builder" · "member" · "viewer" | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/cli/device/{userCode}/approve#
Approve a CLI sign-in for one workspace, with at most the scopes it asked for (console).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: workspace member, in the console only;
admintokens are never made this way
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
userCode | path | string | yes | 1 to 32 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
workspaceId | string | yes | 1 to 128 characters |
scopes | "read" · "write"[] | yes | up to 2 items |
expiresInDays | integer | yes | 1 to 365 |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
status | "approved" · "denied" | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/cli/device/{userCode}/deny#
Refuse a CLI sign-in (console).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: signed in
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
userCode | path | string | yes | 1 to 32 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
status | "approved" · "denied" | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/cli/device/poll#
Ask whether a CLI sign-in was approved; the token comes back once (no sign-in).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: public: the device code is the proof
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
deviceCode | string | yes |
Response 200
A object.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).