> ## Documentation Index
> Fetch the complete documentation index at: https://ventstream.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate ventstreamctl with VentStream Cloud and select the managed organization and environment you want to administer.

This guide is for VentStream Cloud users who administer managed CDC and
realtime pipelines with `ventstreamctl`. Authentication gives the CLI the same
organization-scoped access as the VentStream Cloud dashboard.

<Note>
  The standalone VentStream engine does not require a Cloud account or
  `ventstreamctl`. Run it directly with local configuration when centralized
  administration is not needed.
</Note>

Create an account at [ventstream.dev/signup](https://ventstream.dev/signup), or
accept an invitation from an existing organization, before starting CLI login.

## Sign in from the CLI

Use the control-plane URL supplied for your VentStream Cloud workspace:

```bash theme={null}
ventstreamctl auth login \
  --control-plane <control-plane-url> \
  --profile production
```

The CLI opens the VentStream authorization page in your system browser. Sign in
with your existing account, complete any required MFA or SSO checks, and approve
the CLI session.

The authorization flow uses PKCE, a one-time state value, and a loopback callback
on `127.0.0.1`. Your password is entered only in the browser and is never exposed
to the CLI.

The command also prints the authorization URL. Use `--no-browser` to suppress
automatic launch and open that URL manually on the same workstation:

```bash theme={null}
ventstreamctl auth login \
  --control-plane <control-plane-url> \
  --profile production \
  --no-browser
```

The browser callback expires after five minutes.

## Select an organization and environment

After authentication, the CLI retrieves the organizations and environments that
your account can access:

* A single organization or environment is selected automatically.
* Multiple choices produce an interactive numbered prompt.
* An account with no organization remains authenticated until it accepts an
  invitation or creates an organization in the dashboard.

For a non-interactive terminal, or to select explicitly, pass a UUID, an
unambiguous UUID prefix of at least eight characters, or a slug:

```bash theme={null}
ventstreamctl auth login \
  --control-plane <control-plane-url> \
  --profile production \
  --organization acme \
  --environment production
```

Change the saved context later without signing in again:

```bash theme={null}
ventstreamctl orgs list --profile production
ventstreamctl config set-org <organization-id> --profile production
ventstreamctl environments list --profile production
ventstreamctl config set-env <environment-id> --profile production
ventstreamctl config show --profile production
```

## Enterprise SSO

When enterprise OIDC is enabled for a workspace, the same `auth login` command
uses the configured identity provider. Depending on the provider configuration,
VentStream either completes authorization in the browser or displays a
device-code URL and code.

An identity provider using a private PKI can be trusted with:

```bash theme={null}
ventstreamctl auth login \
  --control-plane <control-plane-url> \
  --profile enterprise \
  --oidc-trust-bundle <ca.pem>
```

## Check the session

Access tokens are short-lived. The CLI automatically refreshes an expiring token
when the profile has a valid refresh session.

```bash theme={null}
ventstreamctl auth status --profile production
ventstreamctl auth whoami --profile production
```

Print and immediately refresh the bearer token only when an integration requires
it:

```bash theme={null}
ventstreamctl auth token --profile production --refresh
```

<Warning>
  `auth token` prints a bearer credential. Never write its output to logs,
  shell-history expansions, or source-controlled files.
</Warning>

## Account recovery

Use [ventstream.dev/forgot-password](https://ventstream.dev/forgot-password) to
request a one-time reset link. A successful password reset revokes existing
Cloud sessions. Run `auth login` again after setting the new password.

## Log out

```bash theme={null}
ventstreamctl auth logout --profile production
```

This revokes the selected first-party refresh session and removes the local
profile. For an enterprise OIDC profile, it removes the local profile but does
not end the identity-provider session.

Use `--all-sessions` with a first-party profile to revoke every refresh session
for the account. Add `--keep-profile` to retain non-secret control-plane and
context defaults.

## Profile storage

Profiles are stored at
`$XDG_CONFIG_HOME/ventstream/ventstreamctl.json` or
`~/.config/ventstream/ventstreamctl.json`. The CLI atomically writes mode-`0600`
files on Unix-like systems and rejects symlinked or overly permissive profile
files. Set `VENTSTREAMCTL_CONFIG` to use an isolated profile file in automation.

See [CLI administration](/docs/fleet/cli) for managed pipeline operations and
scripting guidance.