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

# auth

> Who am I, person sign-in, registration, and recovery — client.auth.

Six methods. Everything else in the client authenticates with the `apiKey` the client was constructed with; this namespace is how a **person** gets a credential in the first place. API detail: [Authentication](/docs/api/authentication).

## me

```ts theme={"system"}
client.auth.me(): Promise<Identity>
```

`GET /v1/me` — who this credential is: principal, organization, scopes, and (for a person) email and role. The first call any client makes, and the reason none of them needs an `org_` id as input.

## session

```ts theme={"system"}
client.auth.session(body: { email?: string; password?: string; organization_id?: string }): Promise<AuthSession>
```

`POST /v1/auth/session`. Two uses of one route:

* **Sign in** with `email` + `password` — answers a short-lived `vt_` bearer `token`, its `expires_at`, and the person's `organizations`.
* **Re-scope**: present an existing `vt_` token (as the client's `apiKey`) with an `organization_id` to switch organizations. An org you are not a member of is a `403`.

The `token` is a bearer credential — never put it in a browser.

## register

```ts theme={"system"}
client.auth.register(body: { email: string; password: string }): Promise<{ object: "auth_user"; email: string; confirmation_required: boolean }>
```

`POST /v1/auth/users`. `confirmation_required: true` means the address must be confirmed by mail before sign-in succeeds — the response never pretends the person is signed in.

## recover

```ts theme={"system"}
client.auth.recover(body: { email: string }): Promise<Acknowledged>
```

`POST /v1/auth/recover`. Begins a password reset. Answers `202` with `{ object, delivery }` **whether or not the address has an account** — do not branch on it; there is nothing to branch on. `delivery` (`sent | undeliverable`) describes the *deployment's* mailer, never the address.

## resetPassword

```ts theme={"system"}
client.auth.resetPassword(body: { token: string; password: string }): Promise<{ object: "auth_password"; updated: boolean }>
```

`POST /v1/auth/password`. Finishes a reset with the token the emailed link carried. A spent or expired token is a `401` — allowed to refuse out loud, since the caller already holds the credential.

## resendConfirmation

```ts theme={"system"}
client.auth.resendConfirmation(body: { email: string }): Promise<Acknowledged>
```

`POST /v1/auth/confirmations`. Re-sends the confirmation mail. Same `202`, same silence about who exists.