Skip to content
Docs menu

Sign-in flows

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.

View .md

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

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.

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

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"}'
{
  "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

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).

3. Poll for the key

curl -s https://cloud.usevenom.dev/api/cli/v1/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "vdc_..."}'
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)
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

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

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)

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.