---
title: Sign-in flows
description: Get a Venom Cloud client key for a CLI or device without pasting one (the device login), and the browser sign-in routes for GitHub, Clerk and single sign-on.
section: cloud
order: 420
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/api/cli/v1, services/nodejs-cloud/lib/cli-login, services/nodejs-cloud/app/(console)/auth, services/nodejs-cloud/components/console/sso.ts, docs/cloud-sso.md, docs/cloud-mesh.md]
features: [cloud.api-cli]
---

Two kinds of sign-in reach Venom Cloud. A program on someone's machine (the venom CLI, your own CLI, an
editor plugin, a kiosk) gets a client key with the **device login**: it shows a short code, the person
approves it in the console, and the program receives a key. People signing in to the console in a browser use
the `/auth/*` routes: GitHub, Clerk, or their org's own identity provider.

## Device login {#device}

The device login is the OAuth 2.0 device authorization grant (RFC 8628) in shape. `venom cloud login` uses
it, and so can any program you write.

```text
program                         Venom Cloud                       person, in a browser
  | POST /api/cli/v1/device  -->  |                                  |
  | <-- device_code, user_code    |                                  |
  | show user_code and the URL    |  <-- opens /device?code=…, picks a key group, approves
  | POST /api/cli/v1/token (poll every 5 s)                          |
  | <-- 400 authorization_pending ... then 200 with the key          |
```

### 1. Start {#device-start}

```bash
curl -s https://cloud.usevenom.dev/api/cli/v1/device \
  -H "Content-Type: application/json" \
  -d '{"client_name": "acme-collections", "client_version": "1.4.0"}'
```

```json
{
  "device_code": "vdc_...",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://cloud.usevenom.dev/device",
  "verification_uri_complete": "https://cloud.usevenom.dev/device?code=BCDF-GHJK",
  "expires_in": 600,
  "interval": 5
}
```

| Field | Type | Rule |
|---|---|---|
| `client_name` | string, required | 1 to 64 characters, no control characters. The key is named `venom cli · <client_name>` (with ` (2)`, ` (3)` while the name is taken) |
| `client_version` | string, optional | at most 32 characters |

Any other field is `400 invalid_request`. Show the person `user_code` and `verification_uri` (or open
`verification_uri_complete`). Keep `device_code` secret: it is what turns into a key. The user code is 8
consonants (`XXXX-XXXX`, no vowels, no `0`/`O` or `1`/`I`); the person can type it in any case, with or without
the dash.

### 2. The person approves {#device-approve}

The console's `/device` page shows the code, the program's name and version, when it started, and a coarse
location ("City, CC", never the IP). The person picks a key group they may create keys in (`keys:write`) and
approves or denies. The console does this through `GET /api/admin/v1/device-authorizations/{user_code}` and
`POST /api/admin/v1/device-authorizations` (see [Admin API: orgs, members and keys](/docs/cloud/api-admin-access.md)).

### 3. Poll for the key {#device-token}

```bash
curl -s https://cloud.usevenom.dev/api/cli/v1/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "vdc_..."}'
```

```python
import time, requests

base = "https://cloud.usevenom.dev"
start = requests.post(f"{base}/api/cli/v1/device", json={"client_name": "acme-collections"}).json()
print(f"Open {start['verification_uri']} and enter {start['user_code']}")

interval = start["interval"]
while True:
    time.sleep(interval)
    r = requests.post(f"{base}/api/cli/v1/token", json={"device_code": start["device_code"]})
    if r.ok:
        login = r.json()
        break
    code = r.json()["error"]["code"]
    if code == "slow_down":
        interval += 5
    elif code != "authorization_pending":
        raise SystemExit(f"login failed: {code}")

key = login["key"]   # vck_..., store it like a password
```

Until the login is approved the answer is `400` with one of these codes:

| `code` | Meaning | Do |
|---|---|---|
| `authorization_pending` | nobody has approved it yet | poll again after `interval` seconds |
| `slow_down` | the last poll came sooner than `interval` (with 0.5 seconds of slack) | add 5 seconds to your interval |
| `access_denied` | the person denied it | stop |
| `expired_token` | 10 minutes passed, the code was already used, or it is unknown | start again |

Once approved, the next poll answers `200` exactly once:

| Field | Value |
|---|---|
| `object` | `cli.login` |
| `cloud_url` | the cloud's origin, to use as the base URL |
| `key`, `key_id`, `key_name` | the new client key (shown only here), its id and name |
| `team_id`, `team_name`, `tenant_id` | where the key lives |
| `policy_key` | the org's policy signing key, for checking `GET /v1/policy` ([Agent and CLI API](/docs/cloud/api-agent.md)) |
| `account` | the approver's sign-in (an email or `github:<login>`) |

The key is made only at this moment, in the same transaction that marks the login used. It belongs to the
person who approved it: their member budgets and personal guardrails apply. If that person is later
deprovisioned through SCIM, logins they approved but that nobody picked up are denied.

Both routes take no credential and are limited per client address: 20 logins started and 120 polls per
minute. Over that: `429 rate_limit_exceeded` with `retry-after`.

## Browser sign-in routes {#browser}

These serve the console's login page. Apps do not call them, but an IdP administrator or a reverse proxy
needs to know them.

| Route | What it does |
|---|---|
| `GET /auth/github?next=/path` | starts GitHub sign-in (only when the deployment has a GitHub OAuth app): a signed state and a PKCE challenge, kept in a 10-minute cookie |
| `GET /auth/github/callback` | GitHub's redirect: checks the state, exchanges the code, checks the allowlist, starts a session as `github:<login>` |
| `POST /auth/clerk/callback` | the Clerk sign-in form posts the Clerk session token here; the console checks it, finds the person's org and role, starts a session as `clerk:<email>`. `404` when Clerk is not configured |
| `POST /auth/sso` | "Sign in with SSO" with a work email: the email's verified domain picks the org, then the browser goes to its IdP |
| `GET /auth/sso/start?org=<org id>` | an org's sign-in link, for IdP app tiles and bookmarks; `test=1` is an owner's test sign-in |
| `GET /auth/sso/oidc/callback` | the OIDC redirect URI every org's IdP is given |
| `GET /auth/sso/saml/{org id}` | the SAML service provider metadata; this URL is also the SP entity ID |
| `POST /auth/sso/saml/{org id}/acs` | the SAML assertion consumer service |

Every sign-in, refused or not, writes a `console.sign_in` or `console.sign_in_refused` audit row.

### Single sign-on URLs {#sso}

Give your identity provider these values (Settings, Single sign-on shows them with your org id filled in):

| What | URL |
|---|---|
| OIDC redirect URI | `https://cloud.usevenom.dev/auth/sso/oidc/callback` |
| SAML SP entity ID and metadata | `https://cloud.usevenom.dev/auth/sso/saml/<org id>` |
| SAML ACS URL | `https://cloud.usevenom.dev/auth/sso/saml/<org id>/acs` |
| Sign-in link (app tiles) | `https://cloud.usevenom.dev/auth/sso/start?org=<org id>` |
| SCIM base URL | `https://cloud.usevenom.dev/scim/v2` ([SCIM API](/docs/cloud/api-scim.md)) |

Sign-ins start at Venom (SP-initiated). A SAML response that answers no request (IdP-initiated) is refused;
point app tiles at the sign-in link instead. An org that requires SSO sends its non-owner members to its
sign-in link.

## Related {#related}

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md#credentials) for what a client key can do.
- [SCIM API](/docs/cloud/api-scim.md) to provision members from the IdP.
- [Cloud quickstart](/docs/getting-started/cloud-quickstart.md) for `venom cloud login` from the CLI.
