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

# Authentication

> Secure user management and access control.

Backdrift provides a fully managed authentication system out of the box. No OAuth configuration, no JWT libraries, no security vulnerabilities.

## What You Get

<CardGroup cols={2}>
  <Card title="User Signup" icon="user-plus">
    Self-service registration with email verification
  </Card>

  <Card title="Secure Login" icon="lock">
    Password authentication with brute-force protection
  </Card>

  <Card title="Password Reset" icon="key">
    Secure password recovery via email
  </Card>

  <Card title="JWT Tokens" icon="ticket">
    Access and refresh tokens with configurable expiry
  </Card>
</CardGroup>

## Roles & Permissions

Define roles in your prompt, and Backdrift enforces them at the API level:

```
"Organization admins can invite members and delete projects.
Members can create tasks but not delete projects.
Viewers can only read data."
```

This generates:

| Role   | Permissions                             |
| ------ | --------------------------------------- |
| admin  | Full CRUD on all entities               |
| member | Create/Read/Update tasks, Read projects |
| viewer | Read-only access                        |

## Authorization Levels

Every endpoint has an authorization level:

| Level           | Description                |
| --------------- | -------------------------- |
| `public`        | No authentication required |
| `authenticated` | Any logged-in user         |
| `admin`         | Users with admin role      |
| `owner`         | Only the resource owner    |

### Example

```
GET /v1/tasks         → authenticated (any user)
POST /v1/tasks        → authenticated (any user)
DELETE /v1/tasks/:id  → owner (only creator can delete)
DELETE /v1/projects   → admin (only admins)
```

## Multi-Tenancy

For SaaS applications, Backdrift automatically isolates data by tenant:

```
"Each organization should have isolated data."
```

This configures:

* **Organization Entity** - Tenant boundary
* **Auto-Filtering** - All queries filtered by org\_id
* **JWT Claims** - Tenant ID embedded in tokens

### How It Works

1. User signs up and creates an organization
2. User's JWT includes `org_id` claim
3. Every API request is filtered by `org_id`
4. User in Org A **cannot** access data from Org B

```python theme={null}
# This happens automatically in every Lambda handler:
def list_tasks(event):
    org_id = get_org_id_from_token(event)
    return db.query(
        table="tasks",
        filter={"org_id": org_id}  # Auto-injected
    )
```

## Password Policies

Backdrift enforces secure password policies:

* Minimum 8 characters
* Requires uppercase letter
* Requires lowercase letter
* Requires number
* Requires special character (optional)

## Token Configuration

| Token Type    | Default Expiry | Configurable |
| ------------- | -------------- | ------------ |
| Access Token  | 1 hour         | Yes          |
| Refresh Token | 30 days        | Yes          |
| ID Token      | 1 hour         | Yes          |

## Using Authentication

### Sign Up

```bash theme={null}
curl -X POST https://your-api.amazonaws.com/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'
```

### Login

```bash theme={null}
curl -X POST https://your-api.amazonaws.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'
```

Response:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}
```

### Make Authenticated Requests

```bash theme={null}
curl https://your-api.amazonaws.com/v1/tasks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

## Coming Soon

* Social login (Google, GitHub, Apple)
* SAML/OIDC federation
* Multi-factor authentication (MFA)
* API keys for machine-to-machine auth

<Card title="Data Modeling" icon="database" href="/capabilities/data-modeling">
  Learn how to define entities and relationships.
</Card>