cclohmar/authelia-api
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
authelia-api/docs/postman/collection.json
cclohmar 8cfd403c14 chore: reorganise docs/ folder for Postman, examples, and OpenAPI spec 
- Moved into docs/:
  docs/postman/collection.json         ← authelia-api.postman_collection.json
  docs/postman/environment.json        ← authelia-api.postman_environment.json
  docs/postman-guide.md                ← POSTMAN_GUIDE.md
  docs/openapi.yml                     ← openapi.yml
  docs/examples/bulk-request.json      ← example_bulk_request.json
- Updated README.md with new paths and docs/ structure
- Updated .dockerignore to reflect new layout
- Removed stale pre-built binary from working tree
2026-07-15 18:03:52 +00:00

395 lines
14 KiB
JSON
Raw Permalink Blame History

{
"info": {
"name": "Authelia API",
"description": "Postman collection for Authelia API — user management and access control policy management.\n\n## Authentication\n- Use Bearer token authentication\n- Initial token: `session.secret` from Authelia configuration.yml\n- Header: `Authorization: Bearer <token>`\n\n## Base URL\n- Default: `http://127.0.0.1:8080`\n\n## Quick Start\n1. Start the container: `docker compose up -d`\n2. Get Bearer token from Authelia config's `session.secret`\n3. Set `bearer_token` in environment\n4. Start with Health Check → try Bulk Create → manage policies\n\n## Notes\n- All user passwords are auto-generated\n- Changes trigger automatic sync to Authelia YAML file\n- SMTP onboarding emails available if configured",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Health Check",
"request": {
"method": "GET",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{base_url}}/api/health",
"host": ["{{base_url}}"],
"path": ["api", "health"]
},
"description": "Health check endpoint. No authentication required.\n\nReturns API status, version, and current timestamp."
},
"response": []
},
{
"name": "List Users",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"url": {
"raw": "{{base_url}}/api/users",
"host": ["{{base_url}}"],
"path": ["api", "users"]
},
"description": "List all users in the system.\n\nReturns an array of user objects with username, display_name, email, groups, disabled status, and timestamps."
},
"response": []
},
{
"name": "Get User",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"url": {
"raw": "{{base_url}}/api/users/:username",
"host": ["{{base_url}}"],
"path": ["api", "users", ":username"],
"variable": [
{
"key": "username",
"value": "john.doe",
"description": "Username to retrieve"
}
]
},
"description": "Get a single user by username.\n\n**Path Parameter:**\n- `username` — the username to look up\n\nReturns 404 if user not found."
},
"response": []
},
{
"name": "Bulk Create Users",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
},
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"users\": [\n {\n \"username\": \"john.doe\",\n \"display_name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"groups\": [\"users\", \"admins\"]\n },\n {\n \"username\": \"jane.smith\",\n \"display_name\": \"Jane Smith\",\n \"email\": \"jane.smith@example.com\",\n \"groups\": [\"users\"]\n }\n ]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/users/bulk",
"host": ["{{base_url}}"],
"path": ["api", "users", "bulk"]
},
"description": "Create multiple users in a single request. Passwords are auto-generated.\n\n**Limits:**\n- Max 1000 users per batch\n- `username`, `display_name`, `email` required\n\n**Response includes:**\n- `success`: boolean\n- `created`: count of successfully created users\n- `users`: array with `placeholder_password` and `status` per user"
},
"response": []
},
{
"name": "Delete User",
"request": {
"method": "DELETE",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"url": {
"raw": "{{base_url}}/api/users/:username",
"host": ["{{base_url}}"],
"path": ["api", "users", ":username"],
"variable": [
{
"key": "username",
"value": "john.doe",
"description": "Username to delete"
}
]
},
"description": "Delete a user by username. Triggers automatic YAML sync.\n\nReturns 404 if user not found."
},
"response": []
},
{
"name": "List Policies",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"url": {
"raw": "{{base_url}}/api/policies",
"host": ["{{base_url}}"],
"path": ["api", "policies"]
},
"description": "List all access control policies.\n\nReturns an array of policy objects with id, name, domain, resources, methods, subjects, policy level, and timestamps."
},
"response": []
},
{
"name": "Create Policy",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
},
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Admin Dashboard Restrictions\",\n \"domain\": [\"*.example.com\", \"secure.example.com\"],\n \"resources\": [\"^/admin/.*$\"],\n \"methods\": [\"POST\", \"PUT\", \"DELETE\"],\n \"subjects\": [\"group:admins\", \"user:admin\"],\n \"policy\": \"two_factor\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/policies",
"host": ["{{base_url}}"],
"path": ["api", "policies"]
},
"description": "Create a new access control policy rule.\n\n**Required fields:** `name`, `domain` (array with at least 1 pattern), `policy`\n\n**Policy levels:** `bypass`, `one_factor`, `two_factor`, `deny`\n\n**Domain patterns** support wildcards: `*.example.com`\n\n**Resources** are regex patterns matched against URL paths.\n\n**Subjects** can be `user:<username>` or `group:<groupname>`.\n\nReturns the created policy with a generated `id` (e.g. `pol_93f8s2`)."
},
"response": []
},
{
"name": "Get Policy",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"url": {
"raw": "{{base_url}}/api/policies/:policy_id",
"host": ["{{base_url}}"],
"path": ["api", "policies", ":policy_id"],
"variable": [
{
"key": "policy_id",
"value": "pol_93f8s2",
"description": "Policy ID (e.g. pol_93f8s2)"
}
]
},
"description": "Get a single policy by its unique ID.\n\nReturns 404 if policy not found."
},
"response": []
},
{
"name": "Update Policy",
"request": {
"method": "PUT",
"header": [
{
"key": "Content-Type",
"value": "application/json"
},
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Admin Dashboard Restrictions\",\n \"domain\": [\"*.example.com\"],\n \"resources\": [\"^/admin/.*$\"],\n \"methods\": [\"POST\", \"PUT\", \"DELETE\"],\n \"subjects\": [\"group:admins\"],\n \"policy\": \"two_factor\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/policies/:policy_id",
"host": ["{{base_url}}"],
"path": ["api", "policies", ":policy_id"],
"variable": [
{
"key": "policy_id",
"value": "pol_93f8s2",
"description": "Policy ID to update"
}
]
},
"description": "Fully replace an existing policy rule. All required fields must be provided.\n\nReturns 404 if policy not found."
},
"response": []
},
{
"name": "Delete Policy",
"request": {
"method": "DELETE",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"url": {
"raw": "{{base_url}}/api/policies/:policy_id",
"host": ["{{base_url}}"],
"path": ["api", "policies", ":policy_id"],
"variable": [
{
"key": "policy_id",
"value": "pol_93f8s2",
"description": "Policy ID to delete"
}
]
},
"description": "Delete a policy by its ID.\n\nReturns 404 if policy not found."
},
"response": []
},
{
"name": "Verify Policy (Dry-run)",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
},
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"domain\": \"secure.example.com\",\n \"path\": \"/admin/dashboard\",\n \"method\": \"POST\",\n \"username\": \"test.user1\",\n \"groups\": [\"developers\", \"admins\"]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/policies/verify",
"host": ["{{base_url}}"],
"path": ["api", "policies", "verify"]
},
"description": "Dry-run policy evaluation — simulate a request and see which policy matches.\n\n**Required:** `domain`, `path`\n**Optional:** `method` (defaults to GET), `username`, `groups`\n\nReturns whether a policy matched, and if so the policy ID, name, and required action level."
},
"response": []
},
{
"name": "Get User Policies",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
}
],
"url": {
"raw": "{{base_url}}/api/users/:username/policies",
"host": ["{{base_url}}"],
"path": ["api", "users", ":username", "policies"],
"variable": [
{
"key": "username",
"value": "john.doe",
"description": "Username to evaluate policies for"
}
]
},
"description": "Get all policies that apply to a specific user. Evaluates both direct username matches (`user:john.doe`) and group membership matches (`group:admins`, `group:users`).\n\nReturns an array of policy matches with match reason (direct or via group).\n\nReturns 404 if user not found."
},
"response": []
}
],
"variable": [
{
"key": "base_url",
"value": "http://127.0.0.1:8080",
"type": "string",
"description": "Base URL for API requests"
},
{
"key": "bearer_token",
"value": "YOUR_SESSION_SECRET_HERE",
"type": "string",
"description": "Bearer token (session.secret from Authelia config)"
}
],
"event": [
{
"listen": "prerequest",
"script": {
"type": "text/javascript",
"exec": [
"// Pre-request script — set dynamic variables here if needed",
"console.log('Request:', pm.request);"
]
}
},
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"// Shared test scripts",
"pm.test('Status code is 2xx', function () {",
" pm.expect(pm.response.code).to.be.oneOf([200, 201, 204]);",
"});",
"",
"// Health check assertions",
"if (pm.request.url.toString().includes('/health')) {",
" pm.test('Health check returns ok', function () {",
" var jsonData = pm.response.json();",
" pm.expect(jsonData.status).to.equal('ok');",
" });",
"}",
"",
"// Bulk create assertions",
"if (pm.request.url.toString().includes('/users/bulk')) {",
" pm.test('Bulk create has expected fields', function () {",
" var jsonData = pm.response.json();",
" pm.expect(jsonData).to.have.property('success');",
" pm.expect(jsonData).to.have.property('created');",
" pm.expect(jsonData).to.have.property('users');",
" });",
"}",
"",
"// Policy verify assertions",
"if (pm.request.url.toString().includes('/policies/verify')) {",
" pm.test('Verify response has matched field', function () {",
" var jsonData = pm.response.json();",
" pm.expect(jsonData).to.have.property('matched');",
" });",
"}"
]
}
}
]
}
Reference in a new issue View git blame Copy permalink