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.
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 passwordUntil 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.
Related
- Venom Cloud APIs overview for what a client key can do.
- SCIM API to provision members from the IdP.
- Cloud quickstart for
venom cloud loginfrom the CLI.