authelia-api/docs/openapi.yml

openapi: 3.0.3
info:
  title: Authelia API Sidecar with Policy Management
  description: >
    An API sidecar for Authelia to manage users and access control policies dynamically.    
  version: 1.0.0
servers:
  - url: http://127.0.0.1:8080
    description: Local development server

security:
  - BearerAuth: []

paths:
  # --- User Management Endpoints ---
  /api/health:
    get:
      summary: Health Check
      security: [] # No auth required
      responses:
        '200':
          description: API status and version
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: dev
                  time:
                    type: string
                    format: date-time
                    example: "2026-04-02T00:00:00Z"

  /api/users:
    get:
      summary: List Users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserResponse'

  /api/users/bulk:
    post:
      summary: Bulk Create Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - users
              properties:
                users:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserCreate'
      responses:
        '200':
          description: Users successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  created:
                    type: integer
                    example: 2
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserCreatedDetails'

  /api/users/{username}:
    delete:
      summary: Delete User
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User deleted successfully
        '404':
          description: User not found

  # --- User Policy Evaluation Endpoint ---
  /api/users/{username}/policies:
    get:
      summary: Get Policies Assigned to User
      description: >
        Evaluates and returns all access control policies that apply to this specific user,
        matching either their direct username (e.g., `user:username`) or any of the groups 
        they belong to (e.g., `group:groupname`).        
      parameters:
        - name: username
          in: path
          required: true
          description: The username to evaluate policies for.
          schema:
            type: string
      responses:
        '200':
          description: A list of policies applicable to the user, including the match criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPolicyMatch'
        '404':
          description: User not found

  # --- Policy Management Endpoints ---
  /api/policies:
    get:
      summary: List Policies
      description: Retrieve all defined access control policies.
      responses:
        '200':
          description: A list of defined access control policies.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Policy'
    post:
      summary: Create Policy
      description: Create a new access control policy rule.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyInput'
      responses:
        '201':
          description: Policy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          description: Invalid policy structure

  /api/policies/{policy_id}:
    get:
      summary: Retrieve Policy details
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Policy found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '404':
          description: Policy not found

    put:
      summary: Update Policy
      description: Update an existing access control policy rule by replacing it.
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyInput'
      responses:
        '200':
          description: Policy updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '404':
          description: Policy not found

    delete:
      summary: Remove Policy
      description: Delete an access control policy.
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Policy deleted successfully
        '404':
          description: Policy not found

  /api/policies/verify:
    post:
      summary: Verify Policy (Dry-run / Matcher Check)
      description: >
        Validates how a simulated request (domain, path, method, subject) 
        would evaluate against the current policy rules.        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
                - path
              properties:
                domain:
                  type: string
                  example: "secure.example.com"
                path:
                  type: string
                  example: "/admin/dashboard"
                method:
                  type: string
                  example: "POST"
                username:
                  type: string
                  example: "test.user1"
                groups:
                  type: array
                  items:
                    type: string
                  example: ["developers", "admins"]
      responses:
        '200':
          description: Simulation completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  matched:
                    type: boolean
                    description: True if a policy matched this pattern.
                    example: true
                  policy_id:
                    type: string
                    description: The ID of the policy rule that was matched.
                    example: "pol_93f8s2"
                  policy_name:
                    type: string
                    example: "Admin Dashboard Restrictions"
                  action_required:
                    type: string
                    enum: [bypass, one_factor, two_factor, deny]
                    example: "two_factor"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

  schemas:
    # --- User Schemas ---
    UserCreate:
      type: object
      required:
        - username
        - display_name
        - email
      properties:
        username:
          type: string
          example: john.doe
        display_name:
          type: string
          example: John Doe
        email:
          type: string
          format: email
          example: john.doe@example.com
        groups:
          type: array
          items:
            type: string
          example: ["users", "admins"]

    UserCreatedDetails:
      allOf:
        - $ref: '#/components/schemas/UserCreate'
        - type: object
          properties:
            placeholder_password:
              type: string
              example: "aB3$fG7!kL9*mN2@pQ"
            status:
              type: string
              example: created

    UserResponse:
      allOf:
        - $ref: '#/components/schemas/UserCreate'
        - type: object
          properties:
            disabled:
              type: boolean
              example: false
            created_at:
              type: string
              example: "2026-04-02 00:00:00"
            updated_at:
              type: string
              example: "2026-04-02 00:00:00"

    # --- Policy Schemas ---
    PolicyInput:
      type: object
      required:
        - name
        - domain
        - policy
      properties:
        name:
          type: string
          description: A human-readable identifier for the policy rule.
          example: "Admin Dashboard Restrictions"
        domain:
          type: array
          description: Domain patterns this policy applies to (supports wildcards).
          items:
            type: string
          example: ["*.example.com", "secure.example.com"]
        resources:
          type: array
          description: Regex or exact match paths.
          items:
            type: string
          example: ["^/admin/.*$"]
        methods:
          type: array
          description: HTTP methods to restrict. If empty, all methods apply.
          items:
            type: string
            enum: [GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD]
          example: ["POST", "PUT", "DELETE"]
        subjects:
          type: array
          description: Specific users or groups this policy applies to.
          items:
            type: array
            items:
              type: string
            example: ["group:admins", "user:test.user1"]
        policy:
          type: string
          description: The required authentication level to grant access.
          enum: [bypass, one_factor, two_factor, deny]
          example: "two_factor"

    Policy:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: Unique system identifier for the policy.
              example: "pol_93f8s2"
        - $ref: '#/components/schemas/PolicyInput'

    UserPolicyMatch:
      type: object
      required:
        - policy_id
        - name
        - match_reason
        - policy
      properties:
        policy_id:
          type: string
          example: "pol_93f8s2"
        name:
          type: string
          example: "Admin Dashboard Restrictions"
        match_reason:
          type: string
          description: Explains if the policy matched due to a direct username rule or a group membership.
          example: "Matched via group membership: admins"
        policy:
          type: string
          enum: [bypass, one_factor, two_factor, deny]
          example: "two_factor"
        domain:
          type: array
          items:
            type: string
          example: ["*.example.com"]
        resources:
          type: array
          items:
            type: string
          example: ["^/admin/.*$"]