authelia-api/docs/postman

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	Collection with all 12 API endpoints
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

# 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

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:

{
  "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:

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):

{
  "matched": true,
  "policy_id": "pol_93f8s2",
  "policy_name": "Admin Dashboard Restrictions",
  "action_required": "two_factor"
}

Response 200 (no match):

{
  "matched": false
}

Get User Policies

Retrieve all policies applicable to a specific user:

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

Response 200:

[
  {
    "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)

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:

{
  "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

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

Response 200:

{
  "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

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

Response 200:

{
  "success": true,
  "message": "User john.doe deleted"
}

Health Check

GET /api/health

Response 200:

{
  "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 — Full API specification
• Source Code — Go source
• Postman Files — Collection and environment
• Examples — Sample request payloads
• Authelia Documentation