---
title: Sign in to the console and the CLI
description: Sign in to the Venom Cloud console with email, GitHub, single sign-on or the operator token, create your first organisation, and approve a venom cloud login from the terminal.
section: cloud
order: 10
audience: [user, operator]
sources: [services/nodejs-cloud/app/(console)/login, services/nodejs-cloud/app/(console)/auth, services/nodejs-cloud/app/(console)/onboarding, services/nodejs-cloud/app/(console)/device, services/nodejs-cloud/components/console/session.ts, services/nodejs-cloud/components/console/clerk.ts, services/nodejs-cloud/components/console/github.ts, cli/src/cloud-command.ts, cli/src/cloud-credentials.ts]
features: [cloud.auth, cloud.cloud, cloud.console-login, cloud.console-auth, cloud.console-device, cloud.console-onboarding]
---

The console has one sign-in page, `/login`, with up to four ways in. Which buttons appear depends on what the
deployment has configured. Every way leads to the same console session, and every sign-in, accepted or refused,
is written to the audit log.

| Sign-in | Shown when | Who it admits |
|---|---|---|
| Continue with email (Clerk) | `CLERK_SECRET_KEY` and `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` are both set | members of an organisation; anyone else is offered to create one |
| Continue with GitHub | `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are both set | GitHub accounts on the deployment's allowlist |
| Sign in with SSO | any organisation has single sign-on enabled, or the URL has `?sso=1` | members whose email is at a verified domain of an organisation with SSO |
| Admin token | always (folded under "Operator? Sign in with the admin token" when another sign-in exists) | the operator of the deployment |

On the hosted Venom Cloud, use email, GitHub or your company's SSO. The admin token is for people running their
own deployment.

## Create an account {#sign-up}

1. Open `/auth/clerk/sign-up` (the "Create an account" link on `/login`) and sign up with your email.
2. If you belong to no organisation yet, the console sends you to `/onboarding`, "Create your organisation".
   Enter a name of 2 to 80 characters. You become its owner, and the organisation gets a `default` key group (a key group holds API keys, daemons, policies and GPU grants,
   not people; the API calls it `team`).
3. You land on Get started (`/get-started`), which walks you through a model source, a gear, the CLI and a test
   request. See [Console home](/docs/cloud/console-home.md).

The onboarding ticket lasts 30 minutes. After that `/onboarding` sends you back to `/login` with "The
organisation setup expired". Sign in again to get a new one.

Invited by someone? Open the link in the invitation email instead. It goes to `/auth/clerk/sign-up`, and you
join their organisation with the role they picked. See [Organisations, members and roles](/docs/cloud/console-orgs-members.md).

## Sign in {#sign-in}

`/login` sends you to [Home](/docs/cloud/home.md) (`/home`) after signing in, or to the page you asked for (`?next=/path`,
same-origin paths only). The operator without an org seat lands on `/dashboard`. Already signed in, `/login` redirects straight there.

- **Email**: `/auth/clerk` shows Clerk's sign-in form. Once Clerk has signed you in, the page posts the Clerk
  session token to `/auth/clerk/callback`, which checks it and starts the console session. A verified primary
  email is required.
- **GitHub**: `/auth/github` sends you to GitHub with a signed state and a PKCE challenge (valid 10 minutes);
  GitHub returns to `/auth/github/callback`. The GitHub token is used for the sign-in and dropped.
- **SSO**: "Sign in with SSO" asks for your work email and posts it to `/auth/sso`. The email's domain picks the
  organisation, and the browser goes to its identity provider. An organisation's own sign-in link is
  `/auth/sso/start?org=<org id>`. Setup is in [Single sign-on and SCIM](/docs/cloud/console-sso.md).
- **Admin token**: paste the token. Five wrong tries from one client (or 100 overall) within 15 minutes block
  the form for 15 minutes.

### Operator or member {#operator-or-member}

An operator who signs in with email (listed in `VENOM_CLOUD_CLERK_ADMINS`) and is also a member of an
organisation chooses how to use the console. After the first such sign-in, `/auth/choose` asks:

- **Continue as operator**: every organisation, with the operator's rights. Your organisation's seat stays your
  workspace in Venom Notes and Tasks.
- **Continue as *Org* member**: only that organisation, with your role in it, exactly like any other member. No
  operator page, action or API route opens in this mode.

The choice is remembered on this browser (an httpOnly cookie, `venom_cloud_signin_as`, for a year), so later
sign-ins skip the question. Switch any time from the account menu: **Use as *Org* member**, or **Switch to
operator**. Switching back to the operator works only while your email or Clerk user id is still listed. Each
switch starts a new session, ends the old one everywhere, and is written to the audit log (`console.sign_in`,
method `switch_mode`; a refused switch is `console.sign_in_refused`). An organisation that requires single sign-on
is not offered as a member choice unless you own it. Operators with no organisation seat, the admin token, GitHub
and everyone who is not a listed operator sign in exactly as before.

A console session lasts 12 hours. Signing out ends it on every instance of the cloud. `/auth/clerk/sign-out`
also ends the Clerk session in this browser (use it to try another Clerk account); it then goes to `/`, or back
to `/login` with the refusal when a sign-in was refused.

### Auth routes {#routes}

| Route | Method | What it does |
|---|---|---|
| `/login` | GET | the sign-in page; `?next=`, `?sso=1` (open the SSO form), `?token=1` (open the token form), `?error=` |
| `/auth/clerk` | GET | Clerk's sign-in; 404 unless Clerk is configured |
| `/auth/clerk/sign-up` | GET | Clerk's sign-up; invitation emails link here |
| `/auth/clerk/sign-out` | GET | ends the Clerk session in the browser |
| `/auth/clerk/callback` | POST | form `token`, `next`: verifies the Clerk session token, picks the role, starts the session |
| `/auth/choose` | GET | `?next=`: operator or member, for a listed operator who is also an organisation member ([above](#operator-or-member)) |
| `/auth/github` | GET | redirects to GitHub's authorize page; `?next=` |
| `/auth/github/callback` | GET | GitHub's return: checks state and allowlist, starts the session |
| `/auth/sso` | POST | form `email`, `next`: finds the org by the email's verified domain, redirects to its IdP |
| `/auth/sso/start` | GET | `?org=<org id>[&next=]`: an organisation's SSO sign-in link |
| `/auth/sso/oidc/callback` | GET | the OIDC redirect URI every organisation's IdP is given |
| `/auth/sso/saml/{tenant}` | GET | the SAML SP metadata; the URL is also the SP entity ID |
| `/auth/sso/saml/{tenant}/acs` | POST | the SAML Assertion Consumer Service |
| `/onboarding` | GET | "Create your organisation", for a signed-in Clerk user in no organisation |
| `/device` | GET | approve or deny a `venom cloud login` (below) |

## Sign in from the terminal: venom cloud login {#cli}

`venom cloud login` signs a machine in without pasting a key. It shows a code, opens `/device` in your browser,
and waits until someone approves it. The console then mints an API key for the key group you pick, and the CLI keeps
it in `~/.venom/cloud.json` (mode 0600).

```bash
venom cloud login                 # opens https://cloud.usevenom.dev/device?code=…
venom cloud status                # cloud, key group, key prefix, pinned policy keys, the policy in use
venom cloud logout                # deletes ~/.venom/cloud.json; revoke the key in the console too
```

In the browser, `/device` asks you to sign in first if needed, then shows the code (it looks like `WDJB-MJHT`),
the machine's name, its venom version, a coarse location and how long ago it asked. Check the code matches your
terminal, pick a key group and press Approve, or Deny. The key is minted at the CLI's next poll and never appears on
the page. Approving needs `keys:write` on the key group (an owner, admin or developer).

| Subcommand or flag | What it does |
|---|---|
| `venom cloud login` | the device login above; also pins your organisation's policy-signing key in `~/.venom/policy-keys` when no administrator installed keys, and fetches the key group's policy |
| `--url <cloud>` | the cloud to sign in to; default `VENOM_CLOUD_URL`, else `https://cloud.usevenom.dev` |
| `--no-browser` | print the link instead of opening it |
| `--trust-new-key` | accept a policy key other than the one pinned before (after a rotation) |
| `venom cloud logout` | deletes `~/.venom/cloud.json`, no network call; the key works until you revoke it under Settings, API keys |
| `venom cloud status` | the cloud, key group and key prefix in use (never the key), the pinned keys, the policy |
| `venom cloud backup`, `venom cloud restore` | an organisation's configuration as JSON and back; needs an owner or admin signed in |

`VENOM_CLOUD_URL` and `VENOM_CLOUD_KEY`, when set, win over `~/.venom/cloud.json`. More on the policy key in
[Policy](/docs/security/policy.md#signed).

## Environment variables {#env}

For people running their own Venom Cloud deployment. The hosted cloud sets these for you.

| Variable | Used by | What it does |
|---|---|---|
| `VENOM_CLOUD_ADMIN_TOKEN` | cloud | the admin API's token and the console's token login; at least 32 characters, or the admin API and console answer 503 "not configured". `make cloud-dev` uses a fixed loopback-only value when unset |
| `VENOM_CLOUD_CONSOLE_PASSWORD` | cloud | the token login's password; falls back to `VENOM_CLOUD_ADMIN_TOKEN` |
| `VENOM_CLOUD_ORIGIN` | cloud | the public origin (`https://cloud.example.com`); default the origin of the request (`x-forwarded-host` behind a proxy) |
| `VENOM_CLOUD_ALT_ORIGINS` | cloud | other origins the same deployment answers on, comma-separated (see [Change the domain](/docs/cloud/self-hosting.md#change-domain)); sign-in always starts on `VENOM_CLOUD_ORIGIN`. Unset: only that one |
| `VENOM_CLOUD_REGION` | cloud | the region label `/api/status` and the cloud's own providers report off Vercel (`VERCEL_REGION` wins); default `sin1` |
| `AUTH_SECRET` | cloud | signs session cookies and OAuth state; default a key derived from the console password |
| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | cloud | turn on GitHub sign-in |
| `VENOM_CLOUD_GITHUB_USERS`, `VENOM_CLOUD_GITHUB_ORGS`, `VENOM_CLOUD_GITHUB_TEAMS` | cloud | GitHub's allowlist: logins; organisations; `org/team-slug[=<venom key group id>\|=admin]`. With no allowlist nobody is admitted |
| `CLERK_SECRET_KEY`, `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_JWT_KEY` | cloud | turn on email sign-in through Clerk; the optional JWT public key (PEM) makes the token check networkless |
| `VENOM_CLOUD_CLERK_ADMINS`, `VENOM_CLOUD_CLERK_TEAMS`, `VENOM_CLOUD_CLERK_DOMAINS` | cloud | Clerk operators (emails or user ids; one who is also an organisation member [chooses operator or member](#operator-or-member)); legacy key group mappings; allowed email domains |
| `VENOM_CLOUD_URL`, `VENOM_CLOUD_KEY` | CLI | the cloud and client key the CLI uses; override `~/.venom/cloud.json` |
| `VENOM_CLOUD_ADMIN_KEY` | CLI | an organisation admin's `vak_` key, for `venom gear new --publish` |
| `VENOM_CLOUD_AUDITOR_TOKEN` | `venom-auditor` | the public mesh auditor's token for the cloud's auditor API; required by the auditor, never logged |

## Troubleshooting {#troubleshooting}

`/login` shows the reason after a refused sign-in (`?error=`):

| Message | Cause and fix |
|---|---|
| Your GitHub account is not on this console's allowlist. | Not in `VENOM_CLOUD_GITHUB_USERS`, `_ORGS` or `_TEAMS`. Ask the operator. |
| Your GitHub account has no role on this console. | Admitted but mapped to no key group or admin. |
| GitHub sign-in expired or was tampered with. | The 10-minute state cookie expired or did not match. Start again. |
| Your Clerk account needs a verified primary email address. | Verify your email in the Clerk form. |
| Your email domain is not allowed on this console. | `VENOM_CLOUD_CLERK_DOMAINS` excludes it. |
| The organisation setup expired. | The 30-minute onboarding ticket ran out. Sign in again. |
| No organisation has single sign-on for that email domain. | The domain is not verified by any organisation, or SSO is off. |
| Your organisation requires single sign-on. | Use Sign in with SSO. Owners keep their other sign-ins. |
| Too many failed attempts. Try again in 15 minutes. | The token login's limit. |
| The audit log is unavailable, so the console cannot sign you in. | The database is down. No session starts without its audit row. |

On `/device`:

| Message | Cause and fix |
|---|---|
| No login is waiting with that code. | Codes expire after 10 minutes. Run `venom cloud login` again. |
| This login was already approved or denied. | Each code decides once. |
| You can't approve logins for that team. | You lack `keys:write` on it; an owner, admin or developer can. |

## Related

- [Console home](/docs/cloud/console-home.md): the Overview and the Get started checklist.
- [Organisations, members and roles](/docs/cloud/console-orgs-members.md)
- [Single sign-on and SCIM](/docs/cloud/console-sso.md)
- [API keys](/docs/cloud/console-api-keys.md): keys made by `venom cloud login` show up there.
- [Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md)
