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

# Authentication and roles

> Web auth, hosted CLI authorization, secure session storage, workspace roles, and invitations.

Mandala uses Supabase Auth for user identity and adds workspace membership, hosted CLI authorization, invitation handoff, and role-checked permissions around it.

## Web sign-in

The web app supports email-link authentication through `/login`, `/sign-up`, and the server callback at `/callback`.

Auth email delivery is routed through the Mandala email foundation so delivery attempts, suppressions, provider results, and callback state can be audited without exposing tokens in logs. `NEXT_PUBLIC_SITE_URL` must match the public deployment so email links return to the correct origin.

Middleware refreshes the Supabase session and protects authenticated product routes. Server Components and route handlers use cookie-backed Supabase clients; privileged maintenance work uses a server-only service-role client.

## Hosted terminal sign-in

Run:

```bash theme={null}
mandala auth login
```

The terminal creates a short-lived device authorization, opens `/cli/authorize` in the browser, and waits. The signed-in user reviews the request and chooses an authorized workspace. The terminal then exchanges the approved request for a revocable CLI session.

The protocol includes:

* bootstrap and inspection of a bounded authorization request;
* explicit browser approval or denial;
* one-time token exchange;
* workspace-bound session credentials;
* refresh and remote revocation;
* expiration and replay protection; and
* audit records for attempts and decisions.

The CLI never receives a Supabase service-role key, connector credential, model key, workflow database URL, or signing secret.

## Local engineering sign-in

For the local stack, use:

```bash theme={null}
mandala auth login --local --email seed@example.com
```

The magic link appears in local Inbucket. This path exists for development and is separate from the hosted browser-authorization flow.

## Local session storage

Saved CLI state follows each operating system's conventions:

* macOS: Application Support
* Linux: XDG config directory
* Windows: `%APPDATA%\Mandala`

On Windows, session tokens are protected with the current account's Data Protection API. Signing out revokes the hosted session when possible and clears the local session and selected workspace.

## Workspace roles

| Role     | Typical access                                                                                         |
| -------- | ------------------------------------------------------------------------------------------------------ |
| Owner    | All workspace, policy, membership, workflow, and approval permissions                                  |
| Admin    | Same platform permission set as owner; some ownership transitions remain separately guarded            |
| Approver | Read, run, approve, edit, reject, request rework, issue execution capability, and execute mock actions |
| Member   | Read workspace context and run workflows                                                               |
| Viewer   | Read-only workspace and workflow access                                                                |
| Agent    | No inherited human-role permissions                                                                    |

Authorization is checked for the exact operation. A user being able to view an item does not imply they can approve or execute it.

## Invitations and membership

Invitations have separate inspect, accept, resend, and revoke routes. Token material is protected by `INVITATION_TOKEN_SECRET`, and the browser handoff preserves the intended workspace across authentication.

Membership transitions are versioned and auditable. Owners and admins manage membership through role-checked database functions; clients cannot update role rows directly.

## Server clients and secrets

Use the cookie-backed server client for normal authenticated work, the browser client only for browser auth interactions, and the service-role client only inside server-only modules.

Secrets in `.env.example` that control auth, invitations, email payloads, session replacement, workers, and account deletion must never use a `NEXT_PUBLIC_` prefix.