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

# vetta auth

> Sign in, inspect the active credential, and sign out.

`vetta auth` manages the **credential**, not a session. It is the only group that runs without one.

Both sign-in paths end at `GET /v1/me`, which resolves the organization from the credential alone — so nothing here asks you for an `org_` id.

## Commands

| Command                          | Description                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------- |
| `vetta auth login`               | Store a credential for this profile. Aliased as `vetta login`.                  |
| `vetta auth register`            | Create a user account from `--email` / `--password`.                            |
| `vetta auth recover`             | Start a password reset for an address.                                          |
| `vetta auth reset-password`      | Finish a reset with the token the emailed link carried.                         |
| `vetta auth resend-confirmation` | Re-send the confirmation mail for an address.                                   |
| `vetta auth whoami`              | Show the active principal, organization, and scopes. Aliased as `vetta whoami`. |
| `vetta auth logout`              | Delete this profile's stored credential. Aliased as `vetta logout`.             |

<Note>
  `login`, `logout`, and `whoami` are also top-level aliases, which is the spelling most examples use. `vetta login` and `vetta auth login` are the same handler.
</Note>

## login

Two ways in. Pass **either** `--api-key`, **or** both `--email` and `--password`.

```bash theme={"system"}
vetta login --api-key sk_live_...              # CI path: a scoped API key
vetta login --email you@acme.com --password ... # person path: exchanges for a session token
```

| Flag         | Description                                               |
| ------------ | --------------------------------------------------------- |
| `--email`    | Email address. Must be passed together with `--password`. |
| `--password` | Password. Must be passed together with `--email`.         |

`--api-key` is a [global flag](/docs/cli/overview#global-flags), which is why it is not in the table above.

The credential is proved and the organization learned in one call **before** anything is written, so a bad credential leaves no profile behind. The profile file is written `0600` and the credential is never printed back — only its 12-character display prefix.

<Warning>
  The `--email` / `--password` path stores a **session token**, which expires. Run `vetta login` again when it does. For CI, use an API key: it does not expire until you revoke it.
</Warning>

## whoami

```bash theme={"system"}
vetta whoami
```

```json theme={"system"}
{
  "profile": "prod",
  "base_url": "https://api.vetta.sh",
  "key_prefix": "sk_test_arhf",
  "principal": { "type": "key", "id": "key_66nnedy98yfx3ygzssfv99p7tf" },
  "organization": {
    "id": "org_gj9xg0gx6bpvdaysqvz68vr7b5",
    "name": "acme-staging",
    "mode": "test"
  },
  "scopes": ["admin"],
  "user": null
}
```

`user` is `null` when the principal is an API key rather than a person. `mode` is `test` for an `sk_test_…` credential and `live` for `sk_live_…`.

## register

```bash theme={"system"}
vetta auth register --email you@acme.com --password ...
```

| Flag         | Description                        |
| ------------ | ---------------------------------- |
| `--email`    | Email address for the new account. |
| `--password` | Password for the new account.      |

Creates the user. Sign in afterwards with `vetta login` to store a credential.

Registering is not the last step: a new organization holds **no plan**, and every command outside billing is refused with `subscription_required` until it has one. Start it with [`vetta plan subscribe`](/docs/cli/billing#the-plan), pay the checkout page it prints, then `vetta plan show` to confirm.

## recover, reset-password, resend-confirmation

The way out of a dead end: a forgotten password, or a confirmation mail that never arrived. All three are **open** routes — they run without a credential, which is the point.

```bash theme={"system"}
vetta auth recover --email you@acme.com
```

```json theme={"system"}
{ "object": "auth_recovery", "delivery": "sent" }
```

The reply is the same **whether or not that address has an account**. There is nothing here to branch on, deliberately: an endpoint that answered differently would be an account-enumeration oracle. `delivery` reports what the mailer just did with the message — `sent`, or `undeliverable` on a deployment with no mailer configured.

The emailed link carries a one-time token. Hand it back with the new password:

```bash theme={"system"}
vetta auth reset-password --token <token-from-the-link> --password ...
```

```json theme={"system"}
{ "object": "auth_password", "updated": true }
```

A token that has expired or already been used is refused, and says so:

```
error: unauthorized: that reset link has expired or was already used (req_t259r7j72x4z1gd6v09p5q1wqg)
```

`resend-confirmation` is the same shape as `recover`, for the address that never got its confirmation:

```bash theme={"system"}
vetta auth resend-confirmation --email you@acme.com
```

```json theme={"system"}
{ "object": "auth_confirmation", "delivery": "sent" }
```

| Command               | Flags                   |
| --------------------- | ----------------------- |
| `recover`             | `--email`               |
| `reset-password`      | `--token`, `--password` |
| `resend-confirmation` | `--email`               |

The same three operations are `client.auth.recover`, `client.auth.resetPassword` and `client.auth.resendConfirmation` in the [SDK](/docs/sdk/typescript#method-index), and are described under [Authentication](/docs/api/authentication) in the API reference.

## logout

```bash theme={"system"}
vetta logout
```

```json theme={"system"}
{ "profile": "prod", "logged_out": true }
```

Removes the credential for the **active profile** only. Other profiles are untouched. Use `--profile <name>` to sign a different one out.

## Profiles

Every `auth` command acts on the profile named by `--profile` (default: the last profile you logged into). This is what stops the next command silently aiming at production:

```bash theme={"system"}
vetta login --profile staging --api-key sk_test_...
vetta whoami --profile staging
```