autehlia-api/authelia-api.postman_collection.json

{
  "info": {
    "name": "Authelia API API",
    "description": "Postman collection for Authelia API REST API\n\nThis API provides a \"Source of Truth\" for Authelia user management with SQLite backend, bulk user onboarding, and automatic synchronization with Authelia's `users_database.yml` file.\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- Can be changed via `--listen` flag\n\n## Quick Start\n1. Install Authelia API using `install.sh`\n2. Start the service: `systemctl start authelia-api`\n3. Get your session.secret from `/opt/authelia/configuration.yml`\n4. Use this collection with the token as environment variable\n\n## Notes\n- All user passwords are auto-generated as secure placeholders\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 to verify API is running. No authentication required."
      },
      "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 automatically generated and returned in the response.\n\n**Limits:**\n- Max 1000 users per request\n- Username, display_name, and email are required\n- Email must contain '@' symbol\n\n**Response includes:**\n- `success`: boolean indicating if any users were created\n- `created`: count of successfully created users\n- `users`: array with status and placeholder_password for each user"
      },
      "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 with pagination support.\n\n**Query Parameters:**\n- `page`: page number (default: 1)\n- `page_size`: items per page (default: 50)\n\n**Note:** Pagination is implemented but currently returns all users. Future versions will support proper pagination."
      },
      "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 sync to update Authelia's YAML file.\n\n**Returns:**\n- `success`: boolean\n- `message`: confirmation message"
      },
      "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 can be used to set dynamic variables",
          "console.log('Request:', pm.request);"
        ]
      }
    },
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Test script to validate responses",
          "pm.test('Status code is 200 or 201', function () {",
          "    pm.expect(pm.response.code).to.be.oneOf([200, 201, 204]);",
          "});",
          "",
          "// For health check, ensure status is ok",
          "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');",
          "    });",
          "}",
          "",
          "// For bulk create, check response structure",
          "if (pm.request.url.toString().includes('/bulk')) {",
          "    pm.test('Bulk create returns success field', 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');",
          "    });",
          "}"
        ]
      }
    }
  ]
}