authelia-api/docs/postman-guide.md

# Authelia API — Postman Collection Guide

Postman files for testing and interacting with the Authelia API (user management + access control policies).

## Files

| File | Description |
|------|-------------|
| [`postman/collection.json`](postman/collection.json) | Collection with all 12 API endpoints |
| [`postman/environment.json`](postman/environment.json) | Environment variables (`base_url`, `bearer_token`) |

## Setup

### 1. Import into Postman

1. Open Postman → **Import** → select both files → **Import**

### 2. Configure Environment

1. Select **"Authelia API"** environment from the dropdown (top-right)
2. Click the eye icon → set variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `base_url` | `http://127.0.0.1:8080` | API address |
| `bearer_token` | *(your token)* | `session.secret` from Authelia config |

### 3. Get Your Bearer Token

```bash
# Extract from Authelia configuration.yml
grep -A2 "session:" /config/configuration.yml | grep "secret:" | awk '{print $2}'
```

Example: `5DdUKe12k6niaaekpTeB0H35A48xmTWBWJcI3AOoqPA=`

> **Security:** This token grants full API access. Keep it secure.

---

## API Endpoints

### User Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/health` | Health check *(no auth)* |
| `GET` | `/api/users` | List all users |
| `GET` | `/api/users/{username}` | Get single user |
| `POST` | `/api/users/bulk` | Bulk create users (max 1000) |
| `DELETE` | `/api/users/{username}` | Delete user |

### Policy Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/policies` | List all policies |
| `POST` | `/api/policies` | Create policy |
| `GET` | `/api/policies/{policy_id}` | Get single policy |
| `PUT` | `/api/policies/{policy_id}` | Update policy |
| `DELETE` | `/api/policies/{policy_id}` | Delete policy |
| `POST` | `/api/policies/verify` | Dry-run policy matching |
| `GET` | `/api/users/{username}/policies` | Get policies for a user |

---

## Examples

### Create Policy

```json
POST /api/policies
Authorization: Bearer <token>

{
  "name": "Admin Dashboard Restrictions",
  "domain": ["*.example.com", "secure.example.com"],
  "resources": ["^/admin/.*$"],
  "methods": ["POST", "PUT", "DELETE"],
  "subjects": ["group:admins", "user:admin"],
  "policy": "two_factor"
}
```

**Response `201`:**
```json
{
  "id": "pol_93f8s2",
  "name": "Admin Dashboard Restrictions",
  "domain": ["*.example.com", "secure.example.com"],
  "resources": ["^/admin/.*$"],
  "methods": ["POST", "PUT", "DELETE"],
  "subjects": ["group:admins", "user:admin"],
  "policy": "two_factor",
  "created_at": "2026-07-15 12:00:00",
  "updated_at": "2026-07-15 12:00:00"
}
```

### Verify Policy (Dry-run)

Test how a request would evaluate against your policies:

```json
POST /api/policies/verify
Authorization: Bearer <token>

{
  "domain": "secure.example.com",
  "path": "/admin/dashboard",
  "method": "POST",
  "username": "test.user1",
  "groups": ["developers", "admins"]
}
```

**Response `200` (matched):**
```json
{
  "matched": true,
  "policy_id": "pol_93f8s2",
  "policy_name": "Admin Dashboard Restrictions",
  "action_required": "two_factor"
}
```

**Response `200` (no match):**
```json
{
  "matched": false
}
```

### Get User Policies

Retrieve all policies applicable to a specific user:

```json
GET /api/users/john.doe/policies
Authorization: Bearer <token>
```

**Response `200`:**
```json
[
  {
    "policy_id": "pol_93f8s2",
    "name": "Admin Dashboard Restrictions",
    "match_reason": "Matched via group membership: admins",
    "policy": "two_factor",
    "domain": ["*.example.com"],
    "resources": ["^/admin/.*$"]
  }
]
```

### Create Users (Bulk)

```json
POST /api/users/bulk
Authorization: Bearer <token>

{
  "users": [
    {
      "username": "john.doe",
      "display_name": "John Doe",
      "email": "john.doe@example.com",
      "groups": ["users", "admins"]
    }
  ]
}
```

**Response `200`:**
```json
{
  "success": true,
  "created": 1,
  "users": [
    {
      "username": "john.doe",
      "display_name": "John Doe",
      "email": "john.doe@example.com",
      "placeholder_password": "aB3$fG7!kL9*mN2@pQ",
      "status": "created"
    }
  ]
}
```

### Get Single User

```json
GET /api/users/john.doe
Authorization: Bearer <token>
```

**Response `200`:**
```json
{
  "username": "john.doe",
  "display_name": "John Doe",
  "email": "john.doe@example.com",
  "groups": ["users", "admins"],
  "disabled": false,
  "created_at": "2026-07-15 12:00:00",
  "updated_at": "2026-07-15 12:00:00"
}
```

### Delete User

```json
DELETE /api/users/john.doe
Authorization: Bearer <token>
```

**Response `200`:**
```json
{
  "success": true,
  "message": "User john.doe deleted"
}
```

### Health Check

```json
GET /api/health
```

**Response `200`:**
```json
{
  "status": "ok",
  "version": "dev",
  "time": "2026-07-15T12:00:00Z"
}
```

---

## Policy Fields Reference

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `name` | ✅ | string | Human-readable identifier |
| `domain` | ✅ | `[]string` | Domain patterns (supports `*` wildcards) |
| `resources` | no | `[]string` | URL path regex patterns |
| `methods` | no | `[]string` | HTTP methods (empty = all) |
| `subjects` | no | `[]string` | `user:<name>` or `group:<name>` patterns |
| `policy` | ✅ | string | `bypass`, `one_factor`, `two_factor`, or `deny` |

### Matching Rules

- **Domain**: glob-style (`*.example.com` matches `secure.example.com`)
- **Resources**: regex matched against URL paths
- **Methods**: exact match (empty array = all methods pass)
- **Subjects**: matched against user's username and group memberships
- **Policy**: the required auth level if all criteria match

---

## Testing Workflow

```
1. Health Check     → Verify API is running
2. Create Policy    → Define an access control rule
3. Get Policies     → Confirm it was created
4. Verify Policy    → Dry-run a request against it
5. Create Users     → Add test users (bulk)
6. Get User Policies → Check which policies apply to user
7. Clean up         → Delete users and policies
```

---

## Troubleshooting

| Error | Likely Cause | Fix |
|-------|-------------|-----|
| `401` | Missing/wrong Bearer token | Check `bearer_token` env var; verify it matches `session.secret` |
| `404` | User or policy not found | Check spelling; list first to confirm ID |
| `400` | Invalid request body | Validate JSON syntax; check required fields |
| Connection refused | API not running | `docker ps`; check `docker compose up -d` |
| Policy `400` | Invalid policy value | Must be one of: `bypass`, `one_factor`, `two_factor`, `deny` |

---

## Related

- [OpenAPI Spec](openapi.yml) — Full API specification
- [Source Code](../src/) — Go source
- [Postman Files](postman/) — Collection and environment
- [Examples](examples/) — Sample request payloads
- [Authelia Documentation](https://www.authelia.com/)