openapi: 3.1.0
info:
  title: Nauthilus IdP API
  version: v1
  description: >
    Public contract for stable Nauthilus IdP routes. It covers OIDC, SAML, and
    browser flow endpoints that are intentionally reachable outside the
    protected backchannel API.
servers:
  - url: "{baseUrl}"
    description: Nauthilus deployment base URL.
    variables:
      baseUrl:
        default: https://nauthilus.example.com
        description: Absolute base URL of the Nauthilus deployment to call.
tags:
  - name: WellKnown
    x-displayName: /.well-known
    description: Public discovery and API contract documents.
  - name: OIDC
    x-displayName: /oidc
    description: OpenID Connect and OAuth 2.0 protocol endpoints.
  - name: SAML
    x-displayName: /saml
    description: SAML Identity Provider protocol endpoints.
  - name: Browser
    x-displayName: /login and /logout
    description: Browser-oriented login, logout, and MFA flow endpoints.
paths:
  /.well-known/openapi.yaml:
    get:
      tags:
        - WellKnown
      operationId: getPublicIdPOpenAPIYAML
      summary: Get the public IdP OpenAPI document as YAML.
      security: []
      responses:
        "200":
          description: OpenAPI document in YAML format.
          content:
            application/yaml:
              schema:
                type: string
  /.well-known/openapi.json:
    get:
      tags:
        - WellKnown
      operationId: getPublicIdPOpenAPIJSON
      summary: Get the public IdP OpenAPI document as JSON.
      security: []
      responses:
        "200":
          description: OpenAPI document in JSON format.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /.well-known/openid-configuration:
    get:
      tags:
        - WellKnown
      operationId: getOIDCDiscovery
      summary: Get OIDC discovery metadata.
      security: []
      responses:
        "200":
          description: OIDC provider metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OIDCDiscovery"
  /oidc/authorize:
    get:
      tags:
        - OIDC
      operationId: authorizeOIDC
      summary: Start or continue an OIDC authorization request.
      security: []
      parameters:
        - $ref: "#/components/parameters/ClientID"
        - $ref: "#/components/parameters/RedirectURI"
        - name: response_type
          in: query
          required: true
          schema:
            type: string
        - name: scope
          in: query
          required: false
          schema:
            type: string
        - name: state
          in: query
          required: false
          schema:
            type: string
        - name: nonce
          in: query
          required: false
          schema:
            type: string
        - name: code_challenge
          in: query
          required: false
          schema:
            type: string
        - name: code_challenge_method
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
        "400":
          $ref: "#/components/responses/Error"
  /oidc/token:
    post:
      tags:
        - OIDC
      operationId: exchangeOIDCToken
      summary: Exchange an OIDC or OAuth token request.
      security:
        - clientBasic: []
        - clientPost: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TokenRequest"
      responses:
        "200":
          description: Token response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "400":
          $ref: "#/components/responses/OAuthError"
        "401":
          $ref: "#/components/responses/OAuthError"
  /oidc/userinfo:
    get:
      tags:
        - OIDC
      operationId: getOIDCUserInfo
      summary: Get OIDC userinfo claims for the bearer token subject.
      security:
        - bearerToken: []
      responses:
        "200":
          description: Userinfo claims.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "401":
          $ref: "#/components/responses/OAuthError"
  /oidc/introspect:
    post:
      tags:
        - OIDC
      operationId: introspectOIDCToken
      summary: Introspect an OAuth token.
      security:
        - clientBasic: []
        - clientPost: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/IntrospectionRequest"
      responses:
        "200":
          description: Token introspection response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntrospectionResponse"
        "400":
          $ref: "#/components/responses/OAuthError"
        "401":
          $ref: "#/components/responses/OAuthError"
  /oidc/jwks:
    get:
      tags:
        - OIDC
      operationId: getOIDCJWKS
      summary: Get the OIDC JSON Web Key Set.
      security: []
      responses:
        "200":
          description: JSON Web Key Set.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JWKS"
  /oidc/device:
    post:
      tags:
        - OIDC
      operationId: startOIDCDeviceAuthorization
      summary: Start the OAuth 2.0 device authorization flow.
      security:
        - clientBasic: []
        - clientPost: []
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                scope:
                  type: string
      responses:
        "200":
          description: Device authorization response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceAuthorizationResponse"
        "400":
          $ref: "#/components/responses/OAuthError"
  /oidc/device/verify:
    get:
      tags:
        - OIDC
      operationId: getOIDCDeviceVerify
      summary: Render the device verification page.
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
    post:
      tags:
        - OIDC
      operationId: postOIDCDeviceVerify
      summary: Submit a device verification code.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /oidc/device/consent:
    get:
      tags:
        - OIDC
      operationId: getOIDCDeviceConsent
      summary: Render the device consent page.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
    post:
      tags:
        - OIDC
      operationId: postOIDCDeviceConsent
      summary: Submit device consent.
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: true
      responses:
        "302":
          $ref: "#/components/responses/Redirect"
  /oidc/logout:
    get:
      tags:
        - OIDC
      operationId: oidcLogout
      summary: Start OIDC logout.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /logout:
    get:
      tags:
        - Browser
      operationId: browserLogout
      summary: Start browser logout.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /oidc/consent:
    get:
      tags:
        - OIDC
      operationId: getOIDCConsent
      summary: Render the OIDC consent page.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
    post:
      tags:
        - OIDC
      operationId: postOIDCConsent
      summary: Submit OIDC consent.
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: true
      responses:
        "302":
          $ref: "#/components/responses/Redirect"
  /saml/metadata:
    get:
      tags:
        - SAML
      operationId: getSAMLMetadata
      summary: Get SAML IdP metadata.
      security: []
      responses:
        "200":
          description: SAML metadata XML.
          content:
            application/samlmetadata+xml:
              schema:
                type: string
            application/xml:
              schema:
                type: string
  /saml/sso:
    get:
      tags:
        - SAML
      operationId: samlSSO
      summary: Start SAML single sign-on.
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /saml/slo:
    get:
      tags:
        - SAML
      operationId: getSAMLSLO
      summary: Start SAML single logout with a redirect binding request.
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
    post:
      tags:
        - SAML
      operationId: postSAMLSLO
      summary: Start SAML single logout with a POST binding request.
      security: []
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /login:
    get:
      tags:
        - Browser
      operationId: getLogin
      summary: Render the primary login page.
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
    post:
      tags:
        - Browser
      operationId: postLogin
      summary: Submit primary login credentials.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/LoginForm"
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /login/totp:
    get:
      tags:
        - Browser
      operationId: getTOTPLogin
      summary: Render the TOTP login page.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
    post:
      tags:
        - Browser
      operationId: postTOTPLogin
      summary: Submit a TOTP login code.
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                code:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /login/webauthn:
    get:
      tags:
        - Browser
      operationId: getWebAuthnLogin
      summary: Render the WebAuthn login page.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
  /login/webauthn/begin:
    get:
      tags:
        - Browser
      operationId: beginWebAuthnLogin
      summary: Begin WebAuthn login.
      security:
        - sessionCookie: []
      responses:
        "200":
          description: Public key credential request options.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /login/webauthn/finish:
    post:
      tags:
        - Browser
      operationId: finishWebAuthnLogin
      summary: Finish WebAuthn login.
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: WebAuthn login result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "400":
          $ref: "#/components/responses/Error"
  /login/mfa:
    get:
      tags:
        - Browser
      operationId: getMFASelection
      summary: Render the MFA method selection page.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
  /login/recovery:
    get:
      tags:
        - Browser
      operationId: getRecoveryLogin
      summary: Render the recovery-code login page.
      security:
        - sessionCookie: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
    post:
      tags:
        - Browser
      operationId: postRecoveryLogin
      summary: Submit a recovery-code login.
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                code:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
        "302":
          $ref: "#/components/responses/Redirect"
  /logged_out:
    get:
      tags:
        - Browser
      operationId: getLoggedOut
      summary: Render the logged-out page.
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HTMLPage"
components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
    clientBasic:
      type: http
      scheme: basic
      description: OIDC client authentication with HTTP Basic.
    clientPost:
      type: apiKey
      in: query
      name: client_secret
      description: OIDC client authentication through form parameters.
    sessionCookie:
      type: apiKey
      in: cookie
      name: nauthilus_secure_data
      description: Encrypted browser session cookie.
  parameters:
    ClientID:
      name: client_id
      in: query
      required: true
      schema:
        type: string
    RedirectURI:
      name: redirect_uri
      in: query
      required: false
      schema:
        type: string
        format: uri
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    HTMLPage:
      description: Browser-facing HTML response.
      content:
        text/html:
          schema:
            type: string
    OAuthError:
      description: OAuth error response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OAuthError"
    Redirect:
      description: Redirect response.
      headers:
        Location:
          schema:
            type: string
  schemas:
    DeviceAuthorizationResponse:
      type: object
      properties:
        device_code:
          type: string
        user_code:
          type: string
        verification_uri:
          type: string
          format: uri
        verification_uri_complete:
          type: string
          format: uri
        expires_in:
          type: integer
        interval:
          type: integer
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        error_description:
          type: string
    IntrospectionRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
        token_type_hint:
          type: string
    IntrospectionResponse:
      type: object
      required:
        - active
      properties:
        active:
          type: boolean
      additionalProperties: true
    JWKS:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            type: object
            additionalProperties: true
    LoginForm:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
          format: password
    OAuthError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        error_description:
          type: string
    OIDCDiscovery:
      type: object
      required:
        - issuer
        - authorization_endpoint
        - token_endpoint
        - jwks_uri
      properties:
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        userinfo_endpoint:
          type: string
          format: uri
        introspection_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
      additionalProperties: true
    TokenRequest:
      type: object
      required:
        - grant_type
      properties:
        grant_type:
          type: string
          enum:
            - authorization_code
            - refresh_token
            - client_credentials
            - urn:ietf:params:oauth:grant-type:device_code
        code:
          type: string
        redirect_uri:
          type: string
          format: uri
        client_id:
          type: string
        client_secret:
          type: string
          format: password
        refresh_token:
          type: string
        device_code:
          type: string
        scope:
          type: string
        code_verifier:
          type: string
        client_assertion_type:
          type: string
          enum:
            - urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        client_assertion:
          type: string
          description: JWT client assertion for private_key_jwt token endpoint authentication.
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_token:
          type: string
        id_token:
          type: string
        scope:
          type: string
