authelia/api/openapi.yml

---
openapi: 3.0.0
info:
  title: Authelia API
  description: >
    Authelia is an open-source authentication and authorization server providing 2-factor authentication and single
    sign-on (SSO) for your applications via a web portal.    
  contact:
    name: Authelia Support
    url: https://github.com/authelia/authelia#contact-options
    email: team@authelia.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
tags:
  - name: State
    description: Configuration, health and state endpoints
  - name: Authentication
    description: Authentication and verification endpoints
  - name: Password Reset
    description: Password reset endpoints
  - name: User Information
    description: User configuration endpoints
  - name: Second Factor
    description: TOTP, U2F and Duo endpoints
paths:
  /api/configuration:
    get:
      tags:
        - State
      summary: Application Configuration
      description: >
        The configuration endpoint provides detailed information including available second factor methods, if any
        second factor policies exist and the TOTP period configuration.        
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.configuration.ConfigurationBody'
        "403":
          description: Forbidden
      security:
        - authelia_auth: []
  /api/health:
    get:
      tags:
        - State
      summary: Application Health
      description: The health check endpoint provides information about the health of Authelia.
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
  /api/state:
    get:
      tags:
        - State
      summary: User Application State
      description: >
        The state endpoint provides detailed information including the user, current authenticate level and Authelia's
        configured default redirection URL.        
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.StateResponse'
  /api/verify:
    get:
      tags:
        - Authentication
      summary: Verification
      description: >
        The verify endpoint provides the ability to verify if a user has the necessary permissions to access a specified
        domain.        
      parameters:
        - $ref: '#/components/parameters/originalURLParam'
        - $ref: '#/components/parameters/forwardedMethodParam'
        - $ref: '#/components/parameters/authParam'
      responses:
        "200":
          description: Successful Operation
          headers:
            remote-user:
              description: Username
              schema:
                type: string
                example: john
            remote-name:
              description: Name
              schema:
                type: string
                example: John Doe
            remote-email:
              description: Email
              schema:
                type: string
                example: john.doe@authelia.com
            remote-groups:
              description: Comma separated list of Groups
              schema:
                type: string
                example: admin,devs
        "401":
          description: Unauthorized
      security:
        - authelia_auth: []
    head:
      tags:
        - Authentication
      summary: Verification
      description: >
        The verify endpoint provides the ability to verify if a user has the necessary permissions to access a specified
        domain.        
      parameters:
        - $ref: '#/components/parameters/originalURLParam'
        - $ref: '#/components/parameters/forwardedMethodParam'
        - $ref: '#/components/parameters/authParam'
      responses:
        "200":
          description: Successful Operation
          headers:
            remote-user:
              description: Username
              schema:
                type: string
                example: john
            remote-name:
              description: Name
              schema:
                type: string
                example: John Doe
            remote-email:
              description: Email
              schema:
                type: string
                example: john.doe@authelia.com
            remote-groups:
              description: Comma separated list of Groups
              schema:
                type: string
                example: admin,devs
        "401":
          description: Unauthorized
      security:
        - authelia_auth: []
  /api/firstfactor:
    post:
      tags:
        - Authentication
      summary: Login
      description: >
        The firstfactor endpoint allows a user to login and generates an authentication cookie for authorization.        
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.firstFactorRequestBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.redirectResponse'
        "401":
          description: Unauthorized
      security:
        - authelia_auth: []
  /api/checks/safe-redirection:
    post:
      tags:
        - Authentication
      summary: Check whether URI is safe to redirect to.
      description: >
        End users usually needs to be redirected to a target website after authentication. This endpoint aims to check
        if target URL is safe to redirect to. This prevents open redirect attacks.        
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.checkURIWithinDomainRequestBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.checkURIWithinDomainResponseBody'
        "401":
          description: Unauthorized
      security:
        - authelia_auth: []
  /api/logout:
    post:
      tags:
        - Authentication
      summary: Logout
      description: The logout endpoint allows a user to logout and destroy a sesssion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.logoutRequestBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.logoutResponseBody'
      security:
        - authelia_auth: []
  /api/reset-password/identity/start:
    post:
      tags:
        - Password Reset
      summary: Identity Verification Token Creation
      description: >
        This endpoint is step 1 of 3 in the password reset process.

        It validates the user session and sends the user an email with a token and a link to reset their password. This
        step also generates a session cookie for the rest of the process.

        The same session cookie must be used for all steps in this process.        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.resetPasswordStep1RequestBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
      security:
        - authelia_auth: []
  /api/reset-password/identity/finish:
    post:
      tags:
        - Password Reset
      summary: Identity Verification Token Validation
      description: >
        This endpoint is step 2 of 3 in the password reset process.

        It validates the user session and reset token.

        The same session cookie must be used for all steps in this process.        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/middlewares.IdentityVerificationFinishBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
      security:
        - authelia_auth: []
  /api/reset-password:
    post:
      tags:
        - Password Reset
      summary: Password Reset
      description: >
        This endpoint is step 3 of 3 in the password reset process.

        It validates the user session and changes the password.

        The same session cookie must be used for all steps in this process.        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.resetPasswordStep2RequestBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
      security:
        - authelia_auth: []
  /api/user/info:
    get:
      tags:
        - User Information
      summary: User Configuration
      description: >
        The user info endpoint provides detailed information including a users display name, preferred and registered
        second factor method(s).        
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.UserInfo'
        "403":
          description: Forbidden
      security:
        - authelia_auth: []
  /api/user/info/2fa_method:
    post:
      tags:
        - User Information
      summary: User Configuration
      description: The user info 2fa_method endpoint sets the users preferred second factor method.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.UserInfo.MethodBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
        "403":
          description: Forbidden
      security:
        - authelia_auth: []
  /api/secondfactor/totp/identity/start:
    post:
      tags:
        - Second Factor
      summary: Identity Verification TOTP Token Creation
      description: >
        This endpoint performs identity verification to begin the TOTP device registration process.

        The session generated from this endpoint must be utilised for the subsequent step in the
        `/api/secondfactor/totp/identity/finish` endpoint.        
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
      security:
        - authelia_auth: []
  /api/secondfactor/totp/identity/finish:
    post:
      tags:
        - Second Factor
      summary: Identity Verification TOTP Token Validation and Device Creation
      description: >
        This endpoint performs identity and token verification, upon success also generates TOTP device secret and
        registers said device.

        The session cookie generated from the `/api/secondfactor/totp/identity/start` endpoint must be utilised for the
        step here.        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/middlewares.IdentityVerificationFinishBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.TOTPKeyResponse'
      security:
        - authelia_auth: []
  /api/secondfactor/totp:
    post:
      tags:
        - Second Factor
      summary: Second Factor Authentication - TOTP
      description: This endpoint performs second factor authentication with a TOTP key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.signTOTPRequestBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.redirectResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.ErrorResponse'
      security:
        - authelia_auth: []
  /api/secondfactor/u2f/sign_request:
    post:
      tags:
        - Second Factor
      summary: Second Factor Authentication - U2F (Request)
      description: This endpoint starts the second factor authentication process with the U2F key.
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/u2f.WebSignRequest'
        "401":
          description: Unauthorized
      security:
        - authelia_auth: []
  /api/secondfactor/u2f/sign:
    post:
      tags:
        - Second Factor
      summary: Second Factor Authentication - U2F
      description: "This endpoint completes second factor authentication with a U2F key."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/handlers.signU2FRequestBody"
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.redirectResponse'
        "401":
          description: Unauthorized
      security:
        - authelia_auth: []
  /api/secondfactor/u2f/identity/start:
    post:
      tags:
        - Second Factor
      summary: Identity Verification U2F Token Creation
      description: >
        This endpoint performs identity verification to begin the U2F device registration process.

        The session generated from this endpoint must be utilised for the subsequent steps in the
        `/api/secondfactor/u2f/identity/finish` and `/api/secondfactor/u2f/register` endpoints.        
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
      security:
        - authelia_auth: []
  /api/secondfactor/u2f/identity/finish:
    post:
      tags:
        - Second Factor
      summary: Identity Verification U2F Token Validation
      description: >
        This endpoint performs identity and token verification, upon success generates a U2F device registration
        challenge.

        The session cookie generated from the `/api/secondfactor/u2f/identity/start` endpoint must be utilised for the
        subsequent steps here and in the `/api/secondfactor/u2f/register` endpoint.        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/middlewares.IdentityVerificationFinishBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/u2f.WebRegisterRequest'
      security:
        - authelia_auth: []
  /api/secondfactor/u2f/register:
    post:
      tags:
        - Second Factor
      summary: U2F Device Registration
      description: This endpoint performs U2F device registration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/u2f.RegisterResponse'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middlewares.OkResponse'
      security:
        - authelia_auth: []
  /api/secondfactor/duo:
    post:
      tags:
        - Second Factor
      summary: Second Factor Authentication - Duo Mobile Push
      description: This endpoint performs second factor authentication with a Duo Mobile Push.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.signDuoRequestBody'
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.redirectResponse'
        "401":
          description: Unauthorized
      security:
        - authelia_auth: []
components:
  parameters:
    originalURLParam:
      name: X-Original-URL
      in: header
      description: Redirection URL
      required: true
      style: simple
      explode: true
      schema:
        type: string
    forwardedMethodParam:
      name: X-Forwarded-Method
      in: header
      description: Request Method
      required: false
      style: simple
      explode: true
      schema:
        type: string
        enum: ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "TRACE", "CONNECT", "OPTIONS"]
    authParam:
      name: auth
      in: query
      description: Switch authorization header and prompt for basic auth
      required: false
      schema:
        type: string
        enum: ["basic"]
  schemas:
    handlers.checkURIWithinDomainRequestBody:
      type: object
      properties:
        uri:
          type: string
          example: https://secure.example.com
    handlers.checkURIWithinDomainResponseBody:
      type: object
      properties:
        ok:
          type: boolean
          example: true
          description: If redirection URL is safe.
    handlers.configuration.ConfigurationBody:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            available_methods:
              type: array
              items:
                type: string
              example: [totp, u2f, mobile_push]
            second_factor_enabled:
              type: boolean
              description: If second factor is enabled.
            totp_period:
              type: integer
              example: 30
    handlers.logoutRequestBody:
      type: object
      properties:
        targetURL:
          type: string
          example: https://redirect.example.com
    handlers.logoutResponseBody:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            safeTargetURL:
              type: boolean
              example: true
    handlers.firstFactorRequestBody:
      required:
        - username
        - password
      type: object
      properties:
        username:
          type: string
          example: john
        password:
          type: string
          example: password
        targetURL:
          type: string
          example: https://home.example.com
        requestMethod:
          type: string
          example: GET
        keepMeLoggedIn:
          type: boolean
          example: true
    handlers.redirectResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            redirect:
              type: string
              example: https://home.example.com
    handlers.resetPasswordStep1RequestBody:
      required:
        - username
      type: object
      properties:
        username:
          type: string
          example: john
    handlers.resetPasswordStep2RequestBody:
      required:
        - password
      type: object
      properties:
        password:
          type: string
          example: password
    handlers.signDuoRequestBody:
      type: object
      properties:
        targetURL:
          type: string
          example: https://secure.example.com
    handlers.signTOTPRequestBody:
      type: object
      properties:
        token:
          type: string
          example: "123456"
        targetURL:
          type: string
          example: https://secure.example.com
    handlers.signU2FRequestBody:
      type: object
      properties:
        targetURL:
          type: string
          example: https://secure.example.com
        signResponse:
          type: object
          properties:
            clientData:
              type: string
              example: 6prxyWqSsR6MXFchtQRzwZVTedWq7Zdc6XreLt6xRDXKeqJN7vzKAfYcKwRD3AT57bP4YFL4hbxat4LUysBNss
            keyHandle:
              type: string
              example: pWgBrwr9meS5vArdffPtD4Px6AqZS7MfGEf776Rz438ujwHjeXwQEZuK53sRQ4wjeAgRCW4wX9VRj8dyKjc273
            signatureData:
              type: string
              example: p3Pe26B6T2E7EEEc59P4p869qwxy8cQAU2ttyGtGrQHb4XL2ZxCpWrawsSHNSTRZQd7jEW59Y3Ku9vSNRzj7Ly
    handlers.StateResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            username:
              type: string
              example: john
            authentication_level:
              type: integer
              example: 1
            default_redirection_url:
              type: string
              example: https://home.example.com
    handlers.TOTPKeyResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            base32_secret:
              type: string
              example: 5ZH7Y5CTFWOXN7EOLGBMMXADRNQFHVUDZSYKCN5HMFAIRSLAWY3Q
            otpauth_url:
              type: string
              example: otpauth://totp/auth.example.com:john?algorithm=SHA1&digits=6&issuer=auth.example.com&period=30&secret=5ZH7Y5CTFWOXN7EOLGBMMXADRNQFHVUDZSYKCN5HMFAIRSLAWY3Q  # yamllint disable-line rule:line-length
    handlers.UserInfo:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            display_name:
              type: string
              example: John Doe
            method:
              type: string
              enum: [totp, u2f, mobile_push]
              example: totp
            has_u2f:
              type: boolean
              example: false
            has_totp:
              type: boolean
              example: true
    handlers.UserInfo.MethodBody:
      required:
        - method
      type: object
      properties:
        method:
          type: string
          enum: [totp, u2f, mobile_push]
          example: totp
    middlewares.ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: KO
        message:
          type: string
          example: Authentication failed, please retry later.
    middlewares.IdentityVerificationFinishBody:
      required:
        - token
      type: object
      properties:
        token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDc5MjU1OTYsImlzcyI6IkF1dGhlbGlhIiwiYWN0aW9uIjoiUmVzZXRQYXNzd29yZCIsInVzZXJuYW1lIjoiQW1pciJ9.636yqRrUCGCe4jsMCsonleX5CYWHncYqZum-YYb6VaY  # yamllint disable-line rule:line-length
    middlewares.OkResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
    u2f.RegisterResponse:
      type: object
      properties:
        version:
          type: string
        registrationData:
          type: string
        clientData:
          type: string
    u2f.WebRegisterRequest:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            appId:
              type: string
              example: https://auth.example.com
            registerRequests:
              type: array
              items:
                type: object
                properties:
                  version:
                    type: string
                    example: U2F_V2
                  challenge:
                    type: string
                    example: XGYKUzSmTpM1KxxpekArviW0w0OU2pwwRAocgn8TkVQ
            registeredKeys:
              type: array
              items:
                type: object
                properties:
                  appId:
                    type: string
                    example: https://auth.example.com
                  version:
                    type: string
                    example: U2F_V2
                  keyHandle:
                    type: string
                    example: pWgBrwr9meS5vArdffPtD4Px6AqZS7MfGEf776Rz438ujwHjeXwQEZuK53sRQ4wjeAgRCW4wX9VRj8dyKjc273
    u2f.WebSignRequest:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            appId:
              type: string
              example: https://auth.example.com
            challenge:
              type: string
              example: XGYKUzSmTpM1KxxpekArviW0w0OU2pwwRAocgn8TkVQ
            registeredKeys:
              type: array
              items:
                type: object
                properties:
                  appId:
                    type: string
                    example: https://auth.example.com
                  version:
                    type: string
                    example: U2F_V2
                  keyHandle:
                    type: string
                    example: pWgBrwr9meS5vArdffPtD4Px6AqZS7MfGEf776Rz438ujwHjeXwQEZuK53sRQ4wjeAgRCW4wX9VRj8dyKjc273
  securitySchemes:
    authelia_auth:
      type: apiKey
      name: "{{.Session}}"
      in: cookie
...