---
title: auth
description: Install the host-owned authentication anchor for users, identities, and sessions.
---

Install `auth` when the Host needs durable users and sessions for application
login. It is the anchor required by every other official auth method.

From a generated host:

```sh
lenso module install auth
cargo run --bin migrate
lenso serve
```

The CLI updates Host composition, dependencies, and local install receipts.
Restart the API and worker after installing or updating modules.

## User model

`auth.users` is the shared authentication anchor. Authenticated business routes
resolve to `ActorContext::User { user_id, scopes }`.

Keep product profile data in your own tables and key it by the auth user id:

```sql
create table app.profiles (
    id text primary key,
    auth_user_id text not null unique,
    display_name text not null,
    created_at timestamptz not null
);
```

Do not add name, avatar, plan, tenant, or organization fields to `auth.users`.
Those belong to the product module. If your product needs different account ids,
store a mapping from the account row to `auth_user_id`.

After restart, use the connected Console's Modules view to verify that `auth`
is loaded. Its Console surface exposes users, sessions, session revocation, and
user enable or disable operations to an authorized operator.

## Console identities are separate

The independent Lenso Console owns its own Auth domain and Service Store. A
business Service user does not automatically become a Console Operator, and
the Console must not read or write this host's Auth tables. Initialize the first
Console Operator with `lenso console operator bootstrap`; manage later
Operators through the Console's identity Module. Development bearer tokens are
local-only.

## Use Redis session lookup

Postgres is the default session lookup backend. Use Redis when session reads
should avoid a database hit:

```sh
lenso module install auth --profile redis-session-cache
```

The profile enables the `redis` feature for `lenso-module-auth`, writes
`REDIS_URL=redis://localhost:6379/0` to `.env`, and records
`auth.session_cache=redis` in `.lenso/runtime-config-defaults.json`.

Provide Redis yourself. The starter Docker Compose file starts Postgres only.

## Development sessions

In local development, `auth` exposes a dev-session route:

```sh
curl -sS -X POST http://127.0.0.1:3000/v1/auth/dev/sessions \
  -H 'content-type: application/json' \
  -d '{"user_id":"usr_demo"}' | jq .
```

Use the returned token as a bearer token:

```sh
curl -sS http://127.0.0.1:3000/v1/app/items \
  -H "authorization: Bearer $LENSO_SESSION_TOKEN" | jq .
```

For quick local work, generated hosts also accept development bearer tokens such
as `Bearer dev-user:usr_demo`. Do not use those in production.

## Manual Rust composition

Most hosts should use `lenso module install`. For hand-written host composition,
use the public builtins exposed by the `host` feature:

```rust
use lenso::host::prelude::*;

pub fn host_composition() -> HostComposition {
    HostBuilder::new()
        .linked_module(builtins::auth())
        .build()
}
```

Run migrations after changing linked module composition:

```sh
cargo run --bin migrate
```