# 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. URL: https://docs.qaldy.com/reference/api/cli/ 5 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/). ## Routes | Method | Path | What it does | |---|---|---| | [[POST]] | [`/​v1/​cli/​device`](#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}`](#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`](#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`](#post-v1-cli-device-usercode-deny) | Refuse a CLI sign-in (console) | | [[POST]] | [`/​v1/​cli/​device/​poll`](#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_only` for 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](https://docs.qaldy.com/reference/api/#errors)). ### [[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_only` for 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](https://docs.qaldy.com/reference/api/#errors)). ### [[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_only` for a token). - **Who:** workspace member, in the console only; `admin` tokens 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](https://docs.qaldy.com/reference/api/#errors)). ### [[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_only` for 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](https://docs.qaldy.com/reference/api/#errors)). ### [[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_only` for 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](https://docs.qaldy.com/reference/api/#errors)).