openapi: 3.0.3
info:
  title: Thunder API Reference
  version: "1.0"
  description: Complete API reference for Thunder identity and access management.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://{host}:{port}
    variables:
      host:
        default: localhost
      port:
        default: "8090"
security:
  - OAuth2:
      - system
tags:
  - name: actions
    description: Operations related to action management at resource server and
      resource levels
  - name: applications
    description: Operations related to application management
  - name: design-resolve
    description: Operations for resolving design configurations
  - name: flow-meta
    description: Operations for retrieving flow metadata
  - name: groups
    description: Operations related to group management
  - name: groups-by-path
    description: Operations related to group management using hierarchical handle paths
  - name: health
    description: Health check operations
  - name: languages
    description: List supported languages
  - name: layouts
    description: Operations related to layout management
  - name: management
    description: Manage translations (admin)
  - name: organization-units
    description: Operations related to organization unit management
  - name: organization-units-by-path
    description: Operations related to organization units using hierarchical handle paths
  - name: permissions
    description: Operations to preview and retrieve derived permissions
  - name: resolve
    description: Resolve translations (runtime)
  - name: resource-servers
    description: Operations related to resource server management
  - name: resources
    description: Operations related to resource management within resource servers
  - name: roles
    description: Operations related to role management
  - name: self
    description: Self service operations related to the user
  - name: themes
    description: Operations related to theme management
  - name: user-schemas
    description: Operations related to user type schema management
  - name: users
    description: Operations related to user management
  - name: users-by-path
    description: Operations related to user management using hierarchical handle paths
paths:
  /applications:
    get:
      tags:
        - applications
      summary: List applications
      description: Retrieve a list of all applications.
      responses:
        "200":
          description: List of applications
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationListResponse"
              example:
                totalResults: 3
                count: 3
                applications:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    name: My Web Application
                    description: Customer portal application
                    clientId: myapp_client_id
                    logoUrl: https://myapp.example.com/logo.png
                    authFlowId: edc013d0-e893-4dc0-990c-3e1d203e005b
                    registrationFlowId: 80024fb3-29ed-4c33-aa48-8aee5e96d522
                    isRegistrationFlowEnabled: true
                  - id: 660e8400-e29b-41d4-a716-446655440001
                    name: Mobile App
                    description: Mobile application for customers
                    clientId: mobile_client_id
                    logoUrl: https://mobileapp.example.com/logo.png
                    authFlowId: edc013d0-e893-4dc0-990c-3e1d203e005b
                    registrationFlowId: 80024fb3-29ed-4c33-aa48-8aee5e96d522
                    isRegistrationFlowEnabled: false
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: APP-1001
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-5001
                message: Internal server error
                description: An unexpected error occurred while processing the request
    post:
      tags:
        - applications
      summary: Create an application
      description: Creates a new application with the provided details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationRequest"
            example:
              ouId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              name: My Web Application
              description: Customer portal application
              authFlowId: edc013d0-e893-4dc0-990c-3e1d203e005b
              registrationFlowId: 80024fb3-29ed-4c33-aa48-8aee5e96d522
              isRegistrationFlowEnabled: true
              url: https://myapp.example.com
              logoUrl: https://myapp.example.com/logo.png
              tosUri: https://myapp.example.com/terms
              policyUri: https://myapp.example.com/privacy
              contacts:
                - admin@myapp.example.com
                - support@myapp.example.com
              metadata:
                env: production
                team: platform
              assertion:
                validityPeriod: 3600
                userAttributes:
                  - email
                  - username
              certificate:
                type: JWKS_URI
                value: https://myapp.example.com/.well-known/jwks
              allowedUserTypes:
                - employee
                - customer
              loginConsent:
                validityPeriod: 3600
              inboundAuthConfig:
                - type: oauth2
                  config:
                    clientId: myapp_client_id
                    clientSecret: myapp_client_secret
                    redirectUris:
                      - https://myapp.example.com/callback
                      - https://myapp.example.com/oauth/callback
                    grantTypes:
                      - authorization_code
                      - refresh_token
                    responseTypes:
                      - code
                    tokenEndpointAuthMethod: client_secret_basic
                    pkceRequired: false
                    publicClient: false
                    scopes:
                      - openid
                      - profile
                      - email
                    token:
                      accessToken:
                        validityPeriod: 3600
                        userAttributes:
                          - email
                          - username
                      idToken:
                        validityPeriod: 3600
                        userAttributes:
                          - email
                          - name
                          - given_name
                          - family_name
                    userInfo:
                      userAttributes:
                        - email
                        - name
                        - given_name
                        - family_name
                        - picture
                    scopeClaims:
                      profile:
                        - name
                        - family_name
                        - given_name
                        - picture
                      employee:
                        - emp_id
                        - department
      responses:
        "201":
          description: Application created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationCompleteResponse"
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                ouId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                name: My Web Application
                description: Customer portal application
                clientId: myapp_client_id
                authFlowId: edc013d0-e893-4dc0-990c-3e1d203e005b
                registrationFlowId: 80024fb3-29ed-4c33-aa48-8aee5e96d522
                isRegistrationFlowEnabled: true
                url: https://myapp.example.com
                logoUrl: https://myapp.example.com/logo.png
                tosUri: https://myapp.example.com/terms
                policyUri: https://myapp.example.com/privacy
                contacts:
                  - admin@myapp.example.com
                  - support@myapp.example.com
                metadata:
                  env: production
                  team: platform
                assertion:
                  validityPeriod: 3600
                  userAttributes:
                    - email
                    - username
                certificate:
                  type: JWKS_URI
                  value: https://myapp.example.com/.well-known/jwks
                allowedUserTypes:
                  - employee
                  - customer
                loginConsent:
                  enabled: true
                  validityPeriod: 3600
                inboundAuthConfig:
                  - type: oauth2
                    config:
                      clientId: myapp_client_id
                      clientSecret: myapp_client_secret
                      redirectUris:
                        - https://myapp.example.com/callback
                        - https://myapp.example.com/oauth/callback
                      grantTypes:
                        - authorization_code
                        - refresh_token
                      responseTypes:
                        - code
                      tokenEndpointAuthMethod: client_secret_basic
                      pkceRequired: false
                      publicClient: false
                      scopes:
                        - openid
                        - profile
                        - email
                      token:
                        accessToken:
                          validityPeriod: 3600
                          userAttributes:
                            - email
                            - username
                        idToken:
                          validityPeriod: 1800
                          userAttributes:
                            - email
                            - email_verified
                            - name
                            - given_name
                            - family_name
                      userInfo:
                        userAttributes:
                          - email
                          - name
                          - given_name
                          - family_name
                          - picture
                      scopeClaims:
                        profile:
                          - name
                          - family_name
                          - given_name
                          - picture
                        employee:
                          - emp_id
                          - department
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: APP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-redirect-uri:
                  summary: Invalid redirect URI
                  value:
                    code: APP-1002
                    message: Invalid redirect URI
                    description: One or more redirect URIs are not valid
                invalid-grant-type:
                  summary: Invalid grant type
                  value:
                    code: APP-1003
                    message: Invalid grant type
                    description: One or more grant types are not supported
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-5001
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /applications/{id}:
    get:
      tags:
        - applications
      summary: Get an application by ID
      description: Retrieve a specific application using its ID.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Application ID
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        "200":
          description: Application details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationGetResponse"
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                ouId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                name: My Web Application
                description: Customer portal application
                clientId: myapp_client_id
                authFlowId: edc013d0-e893-4dc0-990c-3e1d203e005b
                registrationFlowId: 80024fb3-29ed-4c33-aa48-8aee5e96d522
                isRegistrationFlowEnabled: true
                url: https://myapp.example.com
                logoUrl: https://myapp.example.com/logo.png
                tosUri: https://myapp.example.com/terms
                policyUri: https://myapp.example.com/privacy
                contacts:
                  - admin@myapp.example.com
                  - support@myapp.example.com
                metadata:
                  env: production
                  team: platform
                assertion:
                  validityPeriod: 3600
                  userAttributes:
                    - email
                    - username
                certificate:
                  type: JWKS_URI
                  value: https://myapp.example.com/.well-known/jwks
                allowedUserTypes:
                  - employee
                  - customer
                loginConsent:
                  enabled: true
                  validityPeriod: 3600
                inboundAuthConfig:
                  - type: oauth2
                    config:
                      clientId: myapp_client_id
                      redirectUris:
                        - https://myapp.example.com/callback
                        - https://myapp.example.com/oauth/callback
                      grantTypes:
                        - authorization_code
                        - refresh_token
                      responseTypes:
                        - code
                      tokenEndpointAuthMethod: client_secret_basic
                      pkceRequired: false
                      publicClient: false
                      scopes:
                        - openid
                        - profile
                        - email
                      token:
                        accessToken:
                          validityPeriod: 3600
                          userAttributes:
                            - email
                            - username
                        idToken:
                          validityPeriod: 1800
                          userAttributes:
                            - email
                            - email_verified
                            - name
                            - given_name
                            - family_name
                      userInfo:
                        userAttributes:
                          - email
                          - name
                          - given_name
                          - family_name
                          - picture
                      scopeClaims:
                        profile:
                          - name
                          - family_name
                          - given_name
                          - picture
                        employee:
                          - emp_id
                          - department
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-1001
                message: Invalid request format
                description: The request contains invalid data
        "404":
          description: Application not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-1004
                message: Application not found
                description: The application with the specified ID does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-5001
                message: Internal server error
                description: An unexpected error occurred while processing the request
    put:
      tags:
        - applications
      summary: Update an application
      description: Update the details of an existing application.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Application ID
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationRequest"
            example:
              ouId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              name: Updated Web Application
              description: Updated customer portal application
              authFlowId: edc013d0-e893-4dc0-990c-3e1d203e005b
              registrationFlowId: 80024fb3-29ed-4c33-aa48-8aee5e96d522
              isRegistrationFlowEnabled: true
              url: https://myapp.example.com
              logoUrl: https://myapp.example.com/updated-logo.png
              tosUri: https://myapp.example.com/terms
              policyUri: https://myapp.example.com/privacy
              contacts:
                - admin@myapp.example.com
                - support@myapp.example.com
              metadata:
                env: production
                team: platform
              assertion:
                validityPeriod: 3600
                userAttributes:
                  - email
                  - username
              certificate:
                type: JWKS_URI
                value: https://myapp.example.com/.well-known/jwks
              allowedUserTypes:
                - employee
                - customer
              loginConsent:
                validityPeriod: 3600
              inboundAuthConfig:
                - type: oauth2
                  config:
                    clientId: myapp_client_id
                    clientSecret: myapp_updated_secret
                    redirectUris:
                      - https://myapp.example.com/callback
                      - https://myapp.example.com/oauth/callback
                      - https://staging.myapp.example.com/callback
                    grantTypes:
                      - authorization_code
                      - refresh_token
                      - client_credentials
                    responseTypes:
                      - code
                    tokenEndpointAuthMethod: client_secret_basic
                    pkceRequired: false
                    publicClient: false
                    scopes:
                      - openid
                      - profile
                      - email
                    token:
                      accessToken:
                        validityPeriod: 3600
                        userAttributes:
                          - email
                          - username
                      idToken:
                        validityPeriod: 1800
                        userAttributes:
                          - email
                          - email_verified
                          - name
                          - given_name
                          - family_name
                    userInfo:
                      userAttributes:
                        - email
                        - name
                        - given_name
                        - family_name
                        - picture
                    scopeClaims:
                      profile:
                        - name
                        - family_name
                        - given_name
                        - picture
                      employee:
                        - emp_id
                        - department
      responses:
        "200":
          description: Application updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationCompleteResponse"
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                ouId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                name: Updated Web Application
                description: Updated customer portal application
                clientId: myapp_client_id
                authFlowId: edc013d0-e893-4dc0-990c-3e1d203e005b
                registrationFlowId: 80024fb3-29ed-4c33-aa48-8aee5e96d522
                isRegistrationFlowEnabled: true
                url: https://myapp.example.com
                logoUrl: https://myapp.example.com/updated-logo.png
                tosUri: https://myapp.example.com/terms
                policyUri: https://myapp.example.com/privacy
                contacts:
                  - admin@myapp.example.com
                  - support@myapp.example.com
                metadata:
                  env: production
                  team: platform
                assertion:
                  validityPeriod: 3600
                  userAttributes:
                    - email
                    - username
                certificate:
                  type: JWKS_URI
                  value: https://myapp.example.com/.well-known/jwks
                allowedUserTypes:
                  - employee
                  - customer
                loginConsent:
                  enabled: true
                  validityPeriod: 3600
                inboundAuthConfig:
                  - type: oauth2
                    config:
                      clientId: myapp_client_id
                      clientSecret: myapp_updated_secret
                      redirectUris:
                        - https://myapp.example.com/callback
                        - https://myapp.example.com/oauth/callback
                        - https://staging.myapp.example.com/callback
                      grantTypes:
                        - authorization_code
                        - refresh_token
                        - client_credentials
                      responseTypes:
                        - code
                      tokenEndpointAuthMethod: client_secret_basic
                      pkceRequired: false
                      publicClient: false
                      scopes:
                        - openid
                        - profile
                        - email
                      token:
                        accessToken:
                          validityPeriod: 3600
                          userAttributes:
                            - email
                            - username
                        idToken:
                          validityPeriod: 1800
                          userAttributes:
                            - email
                            - email_verified
                            - name
                            - given_name
                            - family_name
                      userInfo:
                        userAttributes:
                          - email
                          - name
                          - given_name
                          - family_name
                          - picture
                      scopeClaims:
                        profile:
                          - name
                          - family_name
                          - given_name
                          - picture
                        employee:
                          - emp_id
                          - department
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: APP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-redirect-uri:
                  summary: Invalid redirect URI
                  value:
                    code: APP-1002
                    message: Invalid redirect URI
                    description: One or more redirect URIs are not valid
        "404":
          description: Application not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-1004
                message: Application not found
                description: The application with the specified ID does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-5001
                message: Internal server error
                description: An unexpected error occurred while processing the request
    delete:
      tags:
        - applications
      summary: Delete an application
      description: Delete an application using its ID.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Application ID
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        "204":
          description: Application deleted successfully
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-1001
                message: Invalid request format
                description: The request contains invalid data
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: APP-5001
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /auth/credentials/authenticate:
    post:
      summary: Authenticate with credentials
      description: Authenticate a user by providing user attributes and credentials.
      tags:
        - Credentials
      requestBody:
        description: Credentials authentication request data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CredentialAuthRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTH-CRED-1001
                message: Empty attributes or credentials
                description: The user attributes or credentials cannot be empty
        "401":
          description: "Unauthorized: Authentication failed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTH-CRED-1002
                message: Invalid credentials
                description: The provided credentials are invalid
        "404":
          description: "Not Found: The user could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1008
                message: User not found
                description: No user found with the provided attributes
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/otp/sms/send:
    post:
      summary: Send a SMS OTP
      description: Send a One Time Password (OTP) to a user's mobile number via SMS
        for authentication.
      tags:
        - SMS OTP
      requestBody:
        description: OTP send request data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendOtpAuthRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendOtpAuthResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-OTP-1002
                message: Invalid recipient
                description: The provided recipient is invalid or empty
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/otp/sms/verify:
    post:
      summary: Verify a SMS OTP
      description: Verify a One Time Password (OTP) sent to a user's mobile number via
        SMS for authentication.
      tags:
        - SMS OTP
      requestBody:
        description: OTP verify request data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyOtpAuthRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-OTP-1005
                message: Invalid OTP
                description: The provided OTP is invalid or empty
        "401":
          description: "Unauthorized: OTP verification failed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-OTP-1006
                message: Incorrect OTP
                description: The provided OTP is incorrect or has expired
        "404":
          description: "Not Found: The user could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1008
                message: User not found
                description: No user found with the provided attributes
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/oauth/google/start:
    post:
      summary: Start Google authentication
      description: Start OAuth authentication flow with a Google identity provider.
      tags:
        - Google
      requestBody:
        description: Google authentication initiation data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPAuthInitRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDPAuthInitResponse"
              example:
                redirectUrl: https://accounts.google.com/o/oauth2/auth?client_id=your-client-id&response_type=code&scope=openid%20email%20profile&redirect_uri=https://yourapp.com/callback
                sessionToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1001
                message: Invalid identity provider ID
                description: The provided identity provider ID is invalid or empty
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/oauth/google/finish:
    post:
      summary: Finish Google authentication
      description: Complete oauth authentication flow with a Google identity provider.
      tags:
        - Google
      requestBody:
        description: Google authentication completion data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPAuthFinishRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1003
                message: Authorization code is required
                description: The authorization code must be provided to complete authentication
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/oauth/github/start:
    post:
      summary: Start Github authentication
      description: Start OAuth authentication flow with a Github identity provider.
      tags:
        - Github
      requestBody:
        description: Github authentication initiation data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPAuthInitRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDPAuthInitResponse"
              example:
                redirectUrl: https://github.com/login/oauth/authorize?client_id=your-client-id&redirect_uri=https://yourapp.com/callback&scope=user
                sessionToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1001
                message: Invalid identity provider ID
                description: The provided identity provider ID is invalid or empty
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/oauth/github/finish:
    post:
      summary: Finish Github authentication
      description: Complete oauth authentication flow with a Github identity provider.
      tags:
        - Github
      requestBody:
        description: Github authentication completion data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPAuthFinishRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1003
                message: Authorization code is required
                description: The authorization code must be provided to complete authentication
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/oauth/standard/start:
    post:
      summary: Start standard OAuth authentication
      description: Start OAuth authentication flow with a standard identity provider.
      tags:
        - Standard
      requestBody:
        description: Standard OAuth IDP authentication initiation data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPAuthInitRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDPAuthInitResponse"
              example:
                redirectUrl: https://your-idp.com/oauth2/authorize?client_id=your-client-id&response_type=code&scope=openid%20email%20profile&redirect_uri=https://yourapp.com/callback
                sessionToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1001
                message: Invalid identity provider ID
                description: The provided identity provider ID is invalid or empty
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/oauth/standard/finish:
    post:
      summary: Finish standard OAuth authentication
      description: Complete oauth authentication flow with a standard identity provider.
      tags:
        - Standard
      requestBody:
        description: Standard OAuth IDP authentication completion data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPAuthFinishRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1003
                message: Authorization code is required
                description: The authorization code must be provided to complete authentication
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/passkey/start:
    post:
      summary: Start WebAuthn authentication
      description: Initiate WebAuthn/Passkey authentication for a user.
      tags:
        - WebAuthn / Passkey
      requestBody:
        description: WebAuthn authentication initiation data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebAuthnStartRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebAuthnStartResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1011
                message: Empty username
                description: The username is required to start WebAuthn authentication
        "404":
          description: "Not Found: The user could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1008
                message: User not found
                description: No user found with the provided User ID
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /auth/passkey/finish:
    post:
      summary: Finish WebAuthn authentication
      description: Complete WebAuthn/Passkey authentication for a user.
      tags:
        - WebAuthn / Passkey
      requestBody:
        description: WebAuthn authentication completion data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebAuthnFinishRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              examples:
                emptyCredentialId:
                  value:
                    code: AUTHN-1012
                    message: Empty credential ID
                    description: The credential ID is required to complete WebAuthn authentication
                emptyCredentialType:
                  value:
                    code: AUTHN-1013
                    message: Empty credential type
                    description: The credential type is required to complete WebAuthn authentication
                invalidAuthenticatorResponse:
                  value:
                    code: AUTHN-1014
                    message: Invalid authenticator response
                    description: The authenticator response is missing required fields
                      (clientDataJSON, authenticatorData, or signature)
                emptySessionToken:
                  value:
                    code: AUTHN-1004
                    message: Empty session token
                    description: The provided session token is empty
        "401":
          description: "Unauthorized: WebAuthn authentication failed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: WEBAUTHN-1008
                message: Invalid signature
                description: The WebAuthn signature verification failed
        "404":
          description: "Not Found: The user or credential could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1008
                message: User not found
                description: No user found for the provided credential
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /design/themes:
    get:
      tags:
        - themes
      summary: List themes
      description: Retrieve a list of all theme configurations.
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of theme configurations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 5
                themes:
                  - id: 019c4e3a-198e-7e4c-99b5-26e327b9bbfc
                    handle: classic
                    displayName: Classic
                    description: A timeless theme with warm accents and readable contrast for
                      programming.
                    createdAt: ""
                    updatedAt: ""
                  - id: 019c4e3a-19ad-7159-bb2b-228692f96008
                    handle: high-contrast
                    displayName: High Contrast
                    description: A high contrast theme optimized for accessibility with bold colors
                      and maximum readability.
                    createdAt: ""
                    updatedAt: ""
                links: []
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
        - themes
      summary: Create theme
      description: Create a new theme configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ThemeRequest"
            example:
              handle: corporate-theme
              displayName: Corporate Theme
              theme:
                primaryColor: "#1976d2"
                secondaryColor: "#dc004e"
                fontFamily: Roboto
                borderRadius: 4px
      responses:
        "201":
          description: Theme created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeResponse"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                handle: corporate-theme
                displayName: Corporate Theme
                theme:
                  primaryColor: "#1976d2"
                  secondaryColor: "#dc004e"
                  fontFamily: Roboto
                  borderRadius: 4px
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /design/themes/{id}:
    get:
      tags:
        - themes
      summary: Get theme
      description: Retrieve a specific theme configuration by ID.
      parameters:
        - $ref: "#/components/parameters/idPathParam"
      responses:
        "200":
          description: Theme configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeResponse"
              example:
                id: 019c4e3a-198e-7e4c-99b5-26e327b9bbfc
                handle: classic
                displayName: Classic
                description: A timeless theme with warm accents and readable contrast for
                  programming.
                theme:
                  direction: ltr
                  defaultColorScheme: light
                  colorSchemes:
                    light:
                      colors:
                        primary:
                          main: "#ff7300"
                          dark: "#cc5c00"
                          contrastText: "#ffffff"
                        secondary:
                          main: "#757575"
                          dark: "#5c5c5c"
                          contrastText: "#ffffff"
                        background:
                          default: "#fafafa"
                          paper: "#ffffff"
                        text:
                          primary: "#000000"
                          secondary: "#444444"
                    dark:
                      colors:
                        primary:
                          main: "#ff7300"
                          dark: "#cc5c00"
                          contrastText: "#ffffff"
                        secondary:
                          main: "#757575"
                          dark: "#5c5c5c"
                          contrastText: "#ffffff"
                        background:
                          default: "#121212"
                          paper: "#1e1e1e"
                        text:
                          primary: "#ffffff"
                          secondary: "#cccccc"
                  shape:
                    borderRadius: 8
                  typography:
                    fontFamily: "'Inter Variable', sans-serif"
                createdAt: ""
                updatedAt: ""
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    put:
      tags:
        - themes
      summary: Update theme
      description: Update an existing theme configuration.
      parameters:
        - $ref: "#/components/parameters/idPathParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ThemeRequest"
            example:
              handle: corporate-theme
              displayName: Updated Corporate Theme
              theme:
                primaryColor: "#1976d2"
                secondaryColor: "#dc004e"
                fontFamily: Inter
                borderRadius: 8px
      responses:
        "200":
          description: Theme updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - themes
      summary: Delete theme
      description: Delete a theme configuration.
      parameters:
        - $ref: "#/components/parameters/idPathParam"
      responses:
        "204":
          description: Theme deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /design/layouts:
    get:
      tags:
        - layouts
      summary: List layouts
      description: Retrieve a list of all layout configurations.
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of layout configurations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayoutListResponse"
              example:
                totalResults: 1
                startIndex: 1
                count: 1
                layouts:
                  - id: 019c50f8-c0d6-7055-8e03-e19bac6ef649
                    handle: modern
                    displayName: Modern
                    description: A clean, modern authentication layout with a centered card
                      experience, soft gradients, and balanced spacing.
                    createdAt: ""
                    updatedAt: ""
                links: []
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
        - layouts
      summary: Create layout
      description: Create a new layout configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LayoutRequest"
            example:
              handle: modern-layout
              displayName: Modern Layout
              layout:
                contentAlignment: center
                maxWidth: 1200px
                showLogo: true
                logoPosition: top
      responses:
        "201":
          description: Layout created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayoutResponse"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                handle: modern-layout
                displayName: Modern Layout
                layout:
                  contentAlignment: center
                  maxWidth: 1200px
                  showLogo: true
                  logoPosition: top
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /design/layouts/{id}:
    get:
      tags:
        - layouts
      summary: Get layout
      description: Retrieve a specific layout configuration by ID.
      parameters:
        - $ref: "#/components/parameters/idPathParam"
      responses:
        "200":
          description: Layout configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayoutResponse"
              example:
                id: 019c50f8-c0d6-7055-8e03-e19bac6ef649
                handle: modern
                displayName: Modern
                description: A clean, modern authentication layout with a centered card
                  experience, soft gradients, and balanced spacing.
                layout:
                  screens:
                    auth:
                      template: centered
                      background:
                        type: gradient
                        value: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
                      spacing:
                        componentGap: 16
                        sectionGap: 24
                      slots:
                        header:
                          enabled: true
                          height: 80
                          padding: 16
                          layout:
                            type: flex
                            direction: row
                            justify: space-between
                            align: center
                          showLogo: true
                          showLanguageSelector: true
                        main:
                          position:
                            anchor: center
                            verticalAlign: center
                          container:
                            maxWidth: 420
                            padding: 24
                            borderRadius: 12
                            elevation: 2
                            background: surface
                          layout:
                            type: stack
                            direction: vertical
                            gap: md
                            align: stretch
                        footer:
                          enabled: true
                          height: 60
                          padding: 16
                          layout:
                            type: flex
                            direction: row
                            justify: center
                            align: center
                          showLinks: true
                    signin:
                      extends: auth
                      slots:
                        main:
                          container:
                            maxWidth: 420
                    signup:
                      extends: auth
                      slots:
                        main:
                          container:
                            maxWidth: 520
                    mfa:
                      extends: auth
                      slots:
                        header:
                          showBackButton: true
                        main:
                          container:
                            maxWidth: 380
                    forgot-password:
                      extends: auth
                      slots:
                        main:
                          container:
                            maxWidth: 400
                    recovery:
                      extends: auth
                      slots:
                        main:
                          container:
                            maxWidth: 400
                    password-reset:
                      extends: auth
                      slots:
                        main:
                          container:
                            maxWidth: 440
                createdAt: ""
                updatedAt: ""
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    put:
      tags:
        - layouts
      summary: Update layout
      description: Update an existing layout configuration.
      parameters:
        - $ref: "#/components/parameters/idPathParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LayoutRequest"
            example:
              handle: modern-layout
              displayName: Updated Modern Layout
              layout:
                contentAlignment: left
                maxWidth: 1400px
                showLogo: true
                logoPosition: left
      responses:
        "200":
          description: Layout updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayoutResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - layouts
      summary: Delete layout
      description: Delete a layout configuration.
      parameters:
        - $ref: "#/components/parameters/idPathParam"
      responses:
        "204":
          description: Layout deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /design/resolve:
    get:
      tags:
        - design-resolve
      summary: Resolve design configuration
      description: >
        Resolves and retrieves the complete design configuration (theme +
        layout) for a given entity.

        This endpoint merges theme and layout preferences, with layout
        preferences taking precedence over theme preferences when there are
        conflicts.
      security: []
      parameters:
        - name: type
          in: query
          description: The type of entity to resolve design for
          required: true
          schema:
            type: string
            enum:
              - APP
              - OU
          example: APP
        - name: id
          in: query
          description: The ID of the entity (application ID or organization unit ID)
          required: true
          schema:
            type: string
            format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        "200":
          description: Resolved design configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesignResolveResponse"
              example:
                theme:
                  direction: ltr
                  defaultColorScheme: dark
                  colorSchemes:
                    dark:
                      palette:
                        primary:
                          main: "#BD93F9"
                layout:
                  header:
                    logo:
                      url: https://example.com/logo.png
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          description: Entity not found or has no design configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: DSR-1004
                message: Application not found
                description: The application with the specified id does not exist
        "500":
          $ref: "#/components/responses/InternalServerError"
  /flow/execute:
    post:
      summary: Execute a flow step
      description: Execute a step in an authentication flow.
      tags:
        - Execute a flow step
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/InitialFlowRequest"
                - $ref: "#/components/schemas/SubSequentFlowRequest"
            examples:
              initialRequest:
                summary: Initial request
                value:
                  applicationId: 550e8400-e29b-41d4-a716-446655440000
                  flowType: AUTHENTICATION
              subSequentRequestExample:
                summary: Subsequent request
                value:
                  executionId: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
                  actionId: basic_auth
                  inputs:
                    username: thor
                    password: thor@123
      responses:
        "200":
          description: Flow step executed successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/IncompleteFlowResponse"
                  - $ref: "#/components/schemas/CompleteFlowResponse"
                  - $ref: "#/components/schemas/ErrorFlowResponse"
              examples:
                incompleteFlow:
                  summary: Incomplete flow (prompt for user input)
                  value:
                    executionId: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
                    flowStatus: PROMPT_ONLY
                    stepId: 3071b6c6-0119-465c-b00b-3a0e6f88a730
                    type: VIEW
                    data:
                      inputs:
                        - ref: input_username
                          identifier: username
                          type: TEXT_INPUT
                          required: true
                        - ref: input_password
                          identifier: password
                          type: PASSWORD_INPUT
                          required: true
                      actions:
                        - ref: action_submit
                          nextNode: node_bs12
                displayOnlyFlow:
                  summary: Incomplete flow (display-only prompt)
                  value:
                    executionId: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
                    flowStatus: INCOMPLETE
                    stepId: 3071b6c6-0119-465c-b00b-3a0e6f88a730
                    type: VIEW
                    data:
                      meta:
                        components:
                          - id: heading_001
                            type: TEXT
                            category: DISPLAY
                            variant: HEADING_3
                            label: You're All Set
                          - id: body_001
                            type: TEXT
                            category: DISPLAY
                            variant: BODY_1
                            label: You have successfully completed the registration.
                      message: You have successfully completed the registration.
                completeFlow:
                  summary: Complete flow
                  value:
                    executionId: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
                    flowStatus: COMPLETE
                    assertion: <jwt_token>
                errorFlow:
                  summary: Erroneous flow
                  value:
                    executionId: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
                    flowStatus: ERROR
                    failureReason: Invalid credentials
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /flows:
    get:
      tags:
        - Flow Management
      summary: List all flows
      description: Retrieves a paginated list of all flow definitions
      operationId: listFlows
      parameters:
        - name: flowType
          in: query
          description: Filter by flow type
          required: false
          schema:
            type: string
            enum:
              - AUTHENTICATION
              - REGISTRATION
        - name: limit
          in: query
          description: Maximum number of flows to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
        - name: offset
          in: query
          description: Number of flows to skip
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: List of flows retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowListResponse"
        "400":
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1001
                message: Invalid pagination parameter
                description: The limit parameter must be between 1 and 100
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    post:
      tags:
        - Flow Management
      summary: Create a new flow
      description: |
        Creates a new flow definition
      operationId: createFlow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FlowDefinitionRequest"
      responses:
        "201":
          description: Flow created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowDefinitionResponse"
        "400":
          description: Invalid flow definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1001
                message: Invalid request format
                description: The request body is malformed or contains invalid data
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /flows/{flowId}:
    get:
      tags:
        - Flow Management
      summary: Get flow by ID
      description: Retrieves a specific flow definition by its unique identifier
      operationId: getFlow
      parameters:
        - name: flowId
          in: path
          required: true
          description: Unique identifier of the flow
          schema:
            type: string
      responses:
        "200":
          description: Flow retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowDefinitionResponse"
        "404":
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1006
                message: Flow not found
                description: The flow with the specified ID does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    put:
      tags:
        - Flow Management
      summary: Update flow
      description: Updates an existing flow definition by its unique identifier
      operationId: updateFlow
      parameters:
        - name: flowId
          in: path
          required: true
          description: Unique identifier of the flow to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FlowDefinitionRequest"
      responses:
        "200":
          description: Flow updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowDefinitionResponse"
        "400":
          description: Invalid flow definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1001
                message: Invalid request format
                description: The request body is malformed or contains invalid data
        "404":
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1006
                message: Flow not found
                description: The flow with the specified ID does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    delete:
      tags:
        - Flow Management
      summary: Delete flow
      description: Deletes an existing flow definition by its unique identifier
      operationId: deleteFlow
      parameters:
        - name: flowId
          in: path
          required: true
          description: Unique identifier of the flow to delete
          schema:
            type: string
      responses:
        "204":
          description: Flow deleted successfully
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1002
                message: Invalid flow ID
                description: The provided flow ID is not a valid UUID
        "409":
          description: Flow cannot be deleted (e.g., it's a default flow or currently in
            use)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1007
                message: Flow cannot be deleted
                description: Cannot delete a default flow or a flow that is currently in use
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /flows/{flowId}/versions:
    get:
      tags:
        - Flow Versioning
      summary: Get flow version history
      description: |
        Retrieves the complete version history of a specific flow.
      operationId: getFlowVersions
      parameters:
        - name: flowId
          in: path
          required: true
          description: Unique identifier of the flow
          schema:
            type: string
      responses:
        "200":
          description: Flow version history retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowVersionListResponse"
        "404":
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1006
                message: Flow not found
                description: The flow with the specified ID does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /flows/{flowId}/versions/{version}:
    get:
      tags:
        - Flow Versioning
      summary: Get specific flow version
      description: Retrieves a specific version of a flow by version number
      operationId: getFlowVersion
      parameters:
        - name: flowId
          in: path
          required: true
          description: Unique identifier of the flow
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: Version number to retrieve
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Flow version retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowVersionResponse"
        "404":
          description: Flow or version not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1006
                message: Version not found
                description: The specified version does not exist for this flow
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /flows/{flowId}/restore:
    post:
      tags:
        - Flow Versioning
      summary: Restore flow to a previous version
      description: >
        Restores a flow to a specific previous version. This creates a new
        version 

        with the content from the specified version.
      operationId: restoreFlowVersion
      parameters:
        - name: flowId
          in: path
          required: true
          description: Unique identifier of the flow
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RestoreVersionRequest"
      responses:
        "200":
          description: Flow restored successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowVersionResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1001
                message: Invalid version
                description: The specified version number is invalid
        "404":
          description: Flow or version not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientError"
              example:
                code: FMS-1006
                message: Version not found
                description: The specified version does not exist for this flow
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /flow/meta:
    get:
      tags:
        - flow-meta
      security: []
      summary: Get flow metadata
      description: >
        Retrieves aggregated metadata for a flow, including:

        - Application or OU details based on type

        - Resolved design configuration (theme and layout)

        - i18n translations based on language and namespace filters

        - Registration flow enablement status


        **Note:** When `type=APP`, the OU metadata is only included in the
        response

        when the deployment has exactly one organization unit (i.e.,
        `totalResults == 1`).

        For deployments with multiple OUs, the OU metadata will be omitted from
        APP-type responses.
      operationId: getFlowMetadata
      parameters:
        - name: type
          in: query
          required: true
          description: The type of entity to retrieve metadata for
          schema:
            type: string
            enum:
              - APP
              - OU
          example: APP
        - name: id
          in: query
          required: true
          description: The UUID of the entity (application ID or organization unit ID)
          schema:
            type: string
            format: uuid
          example: 60a9b38b-6eba-9f9e-55f9-267067de4680
        - name: language
          in: query
          required: false
          description: Language tag in BCP 47 format for i18n translations (e.g., `en`,
            `es`, `fr-CA`)
          schema:
            type: string
            pattern: ^[a-z]{2}(-[A-Z]{2})?(-[A-Za-z]+)?$
          example: en
        - name: namespace
          in: query
          required: false
          description: Filter translations by namespace (e.g., `auth`, `errors`, `common`)
          schema:
            type: string
            pattern: ^[a-zA-Z0-9_-]+$
          example: auth
      responses:
        "200":
          description: Flow metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowMetadataResponse"
              examples:
                app-metadata:
                  summary: Application metadata with i18n
                  value:
                    isRegistrationFlowEnabled: true
                    application:
                      id: 60a9b38b-6eba-9f9e-55f9-267067de4680
                      name: My Web Application
                      description: My web application for managing resources
                      logoUrl: https://myapp.example.com/logo.png
                      url: https://myapp.example.com
                      tosUri: https://myapp.example.com/terms
                      policyUri: https://myapp.example.com/privacy
                    ou:
                      id: fe447a2f-29c5-4e33-ac8f-d77be15fdb32
                      handle: default
                      name: Default Organization Unit
                      logoUrl: https://myapp.example.com/logo.png
                      tosUri: https://myapp.example.com/terms
                      policyUri: https://myapp.example.com/privacy
                      cookiePolicyUri: https://myapp.example.com/cookies
                    design:
                      theme:
                        direction: ltr
                        defaultColorScheme: dark
                        colorSchemes:
                          dark:
                            palette:
                              primary:
                                main: "#BD93F9"
                      layout:
                        header:
                          logo:
                            url: https://example.com/logo.png
                    i18n:
                      languages:
                        - en
                        - es
                      language: en
                      totalResults: 3
                      translations:
                        auth:
                          login.button: Login
                          login.title: Welcome
                          logout.button: Logout
                ou-metadata:
                  summary: Organization unit metadata
                  value:
                    isRegistrationFlowEnabled: false
                    ou:
                      id: fe447a2f-29c5-4e33-ac8f-d77be15fdb32
                      handle: default
                      name: Default Organization Unit
                      logoUrl: https://myapp.example.com/logo.png
                    design:
                      theme: {}
                      layout: {}
                    i18n:
                      languages:
                        - en
                      language: en
                      totalResults: 0
                      translations: {}
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /groups:
    get:
      tags:
        - groups
      summary: List groups
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeGroupQueryParam"
      responses:
        "200":
          description: List of groups
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                groups:
                  - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    name: Sports
                    description: Sports group
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                  - id: 257e528f-eb24-48b6-884d-20460e190957
                    name: Managers
                    description: Manager group
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                links:
                  - href: groups?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: GRP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: GRP-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: GRP-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
    post:
      tags:
        - groups
      summary: Create a new group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGroupRequest"
            example:
              name: Sports
              description: Sports group
              ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
              members:
                - type: user
                  id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                - type: user
                  id: 9f1e47d3-0347-4464-9f02-e0bfae02e896
                - type: group
                  id: 6b1e7b8d-7e19-41eb-8fa2-c0ee5bb67a94
      responses:
        "201":
          description: Group created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Sports
                description: Sports group
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: GRP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-user-id:
                  summary: Invalid member ID
                  value:
                    code: GRP-1007
                    message: Invalid member ID
                    description: One or more member IDs in the request do not exist
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: GRP-1005
                    message: Organization unit not found
                    description: Organization unit not found
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1004
                message: Group name conflict
                description: A group with the same name exists under the same organization unit
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
  /groups/{id}:
    get:
      tags:
        - groups
      summary: Get a group by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/includeGroupQueryParam"
      responses:
        "200":
          description: Group details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Sports
                description: Sports group
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1002
                message: Invalid request format
                description: Group ID is required
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1003
                message: Group not found
                description: The group with the specified id does not exist
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
    put:
      tags:
        - groups
      summary: Update a group by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGroupRequest"
            example:
              name: Activities
              description: Activities group
              ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
      responses:
        "200":
          description: Group updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Activities
                description: Activities group
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-group-id:
                  summary: Missing group ID
                  value:
                    code: GRP-1002
                    message: Invalid request format
                    description: Group ID is required
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: GRP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: GRP-1005
                    message: Organization unit not found
                    description: Organization unit not found
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1003
                message: Group not found
                description: The group with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1004
                message: Group name conflict
                description: A group with the same name exists under the same organization unit
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
    delete:
      tags:
        - groups
      summary: Delete a group by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Group deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-group-id:
                  summary: Missing group ID
                  value:
                    code: GRP-1002
                    message: Invalid request format
                    description: Group ID is required
                cannot-delete-group:
                  summary: Cannot delete group
                  value:
                    code: GRP-1006
                    message: Cannot delete group
                    description: Cannot delete group with child groups
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
  /groups/{id}/members:
    get:
      tags:
        - groups
      summary: List members in group
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: List of members in the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemberListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                members:
                  - type: user
                    id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                  - type: group
                    id: 8c2f8e9e-8f2a-4f5b-9c3d-4e5f6a7b8c9d
                links:
                  - href: groups/3fa85f64-5717-4562-b3fc-2c963f66afa6/members?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: GRP-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: GRP-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1003
                message: Group not found
                description: The group with the specified id does not exist
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
  /groups/{id}/members/add:
    post:
      tags:
        - groups
      summary: Add members to a group
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MembersRequest"
            example:
              members:
                - type: user
                  id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                - type: user
                  id: 9f1e47d3-0347-4464-9f02-e0bfae02e896
      responses:
        "200":
          description: Members added successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Engineering
                description: Engineering group
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: GRP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                empty-members:
                  summary: Empty members list
                  value:
                    code: GRP-1013
                    message: Empty members list
                    description: The members list cannot be empty
                invalid-member-id:
                  summary: Invalid member ID
                  value:
                    code: GRP-1007
                    message: Invalid user member ID
                    description: One or more user member IDs in the request do not exist
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1003
                message: Group not found
                description: The group with the specified id does not exist
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
  /groups/{id}/members/remove:
    post:
      tags:
        - groups
      summary: Remove members from a group
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MembersRequest"
            example:
              members:
                - type: user
                  id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
      responses:
        "200":
          description: Members removed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Engineering
                description: Engineering group
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: GRP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                empty-members:
                  summary: Empty members list
                  value:
                    code: GRP-1013
                    message: Empty members list
                    description: The members list cannot be empty
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1003
                message: Group not found
                description: The group with the specified id does not exist
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
  /groups/tree/{path}:
    get:
      tags:
        - groups-by-path
      summary: List groups in organization unit specified by handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Lists groups in the "engineering" OU

            - `engineering/frontend` - Lists groups in "engineering/frontend"
          example: engineering/frontend
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeGroupQueryParam"
      responses:
        "200":
          description: List of groups in the organization unit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                groups:
                  - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    name: Sports
                    description: Sports group
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                  - id: 257e528f-eb24-48b6-884d-20460e190957
                    name: Managers
                    description: Manager group
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                links:
                  - href: groups/tree/engineering/frontend?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: GRP-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: GRP-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: GRP-1008
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: GRP-1009
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
    post:
      tags:
        - groups-by-path
      summary: Create a new group under the organization unit specified by the handle
        path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            The new group will be created under the organization unit specified
            by this path.

            Examples:

            - `engineering` - Creates a new group under the "engineering" OU

            - `engineering/frontend` - Creates a new group under
            "engineering/frontend"
          example: engineering/frontend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGroupByPathRequest"
            example:
              name: Sports
              description: Sports group
              members:
                - type: user
                  id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                - type: user
                  id: 9f1e47d3-0347-4464-9f02-e0bfae02e896
                - type: group
                  id: 6b1e7b8d-7e19-41eb-8fa2-c0ee5bb67a94
      responses:
        "201":
          description: Group created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Sports
                description: Sports group
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: GRP-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-member-id:
                  summary: Invalid member ID
                  value:
                    code: GRP-1007
                    message: Invalid member ID
                    description: One or more member IDs in the request do not exist
                parent-path-not-found:
                  summary: Organization unit path not found
                  value:
                    code: GRP-1008
                    message: Organization unit handle path not found
                    description: The specified organization unit handle path does not exist
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: GRP-1008
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: GRP-1009
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: GRP-1004
                message: Group name conflict
                description: A group with the same name exists under the same organization unit
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
  /health/liveness:
    get:
      tags:
        - health
      summary: Liveness Check
      responses:
        "200":
          description: OK
        "503":
          description: Service Unavailable
  /health/readiness:
    get:
      tags:
        - health
      summary: Readiness check
      description: Returns OK if the service is ready to accept traffic.
      responses:
        "200":
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
              example:
                status: UP
                serviceStatus:
                  - serviceName: ConfigDB
                    status: UP
                  - serviceName: RuntimeDB
                    status: UP
                  - serviceName: UserDB
                    status: UP
        "503":
          description: Service is not ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
              example:
                status: DOWN
                serviceStatus:
                  - serviceName: ConfigDB
                    status: DOWN
                  - serviceName: RuntimeDB
                    status: UP
                  - serviceName: UserDB
                    status: UP
  /i18n/languages:
    get:
      tags:
        - languages
      security: []
      summary: List all languages
      description: Returns a list of all language tags that have translations in the system.
      operationId: listLanguages
      responses:
        "200":
          description: List of language tags retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageListResponse"
              examples:
                multiple-languages:
                  summary: Multiple languages
                  value:
                    languages:
                      - en
                      - es
                      - fr
                      - fr-CA
                default-only:
                  summary: Default language only
                  value:
                    languages:
                      - en
        "500":
          $ref: "#/components/responses/InternalServerError"
  /i18n/languages/{language}/translations/resolve:
    parameters:
      - $ref: "#/components/parameters/languagePathParam"
    get:
      tags:
        - resolve
      security: []
      summary: Resolve all translations for a language
      description: Resolves all translations for a language by merging custom and
        default values; returns 200 even when only defaults exist (404 only if
        neither custom nor default exists for the requested scope).
      operationId: resolveTranslations
      parameters:
        - name: namespace
          in: query
          required: false
          description: Filter translations by namespace.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9_-]+$
            example: auth
      responses:
        "200":
          description: Translations resolved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageTranslationsResponse"
              examples:
                all-namespaces:
                  summary: All namespaces for Spanish
                  value:
                    language: es
                    totalResults: 5
                    translations:
                      auth:
                        login.button: Iniciar sesión
                        login.title: Bienvenido
                        logout.button: Cerrar sesión
                      errors:
                        user.not_found: Usuario no encontrado
                        invalid.input: Entrada inválida
                filtered-namespace:
                  summary: Filtered by namespace
                  value:
                    language: es
                    totalResults: 3
                    translations:
                      auth:
                        login.button: Iniciar sesión
                        login.title: Bienvenido
                        logout.button: Cerrar sesión
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /i18n/languages/{language}/translations:
    parameters:
      - $ref: "#/components/parameters/languagePathParam"
    post:
      tags:
        - management
      summary: Set translations for a language
      description: Replaces all custom translations for the language with the provided
        values.
      operationId: setTranslations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetTranslationsRequest"
            example:
              translations:
                auth:
                  login.button: Iniciar sesión
                  login.title: Bienvenido
                  logout.button: Cerrar sesión
                errors:
                  user.not_found: Usuario no encontrado
                  invalid.input: Entrada inválida
                common:
                  save: Guardar
                  cancel: Cancelar
      responses:
        "200":
          description: Custom translations set successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageTranslationsResponse"
              example:
                language: es
                totalResults: 7
                translations:
                  auth:
                    login.button: Iniciar sesión
                    login.title: Bienvenido
                    logout.button: Cerrar sesión
                  errors:
                    user.not_found: Usuario no encontrado
                    invalid.input: Entrada inválida
                  common:
                    save: Guardar
                    cancel: Cancelar
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - management
      summary: Clear all translations for a language
      description: Removes all custom translations for the language.
      operationId: deleteTranslations
      responses:
        "204":
          description: Translations reset to default successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /i18n/languages/{language}/translations/ns/{namespace}/keys/{key}/resolve:
    parameters:
      - $ref: "#/components/parameters/languagePathParam"
      - $ref: "#/components/parameters/namespacePathParam"
      - $ref: "#/components/parameters/keyPathParam"
    get:
      tags:
        - resolve
      security: []
      summary: Resolve a single translation
      description: Resolves the final value for a translation by merging custom and
        default values; returns 200 even when only a default exists (404 only if
        neither custom nor default exists).
      operationId: resolveTranslation
      responses:
        "200":
          description: Translation resolved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranslationResponse"
              example:
                language: es
                namespace: errors
                key: user.not_found
                value: Usuario no encontrado
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /i18n/languages/{language}/translations/ns/{namespace}/keys/{key}:
    parameters:
      - $ref: "#/components/parameters/languagePathParam"
      - $ref: "#/components/parameters/namespacePathParam"
      - $ref: "#/components/parameters/keyPathParam"
    post:
      tags:
        - management
      summary: Set a single translation
      description: Creates or updates a custom translation for the specified language,
        namespace, and key.
      operationId: setTranslation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetTranslationRequest"
            example:
              value: Usuario no encontrado
      responses:
        "200":
          description: Translation set successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranslationResponse"
              example:
                language: es
                namespace: errors
                key: user.not_found
                value: Usuario no encontrado
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - management
      summary: Clear a single translation
      description: Removes the custom translation.
      operationId: deleteTranslation
      responses:
        "204":
          description: Translations reset to default successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /identity-providers:
    get:
      summary: List identity providers
      description: Retrieve a list of all identity providers.
      tags:
        - Identity Providers
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDPListResponse"
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
    post:
      summary: Create an identity provider
      description: Creates a new identity provider with the provided details.
      tags:
        - Identity Providers
      requestBody:
        description: Identity provider data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPRequest"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDPResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1007
                message: Invalid request format
                description: The request body is malformed or contains invalid data
        "409":
          description: "Conflict: An identity provider with the same name already exists."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1004
                message: Identity provider already exists
                description: An identity provider with the same name already exists
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /identity-providers/{id}:
    get:
      summary: Get an identity provider by ID
      description: Retrieve a specific identity provider using its ID.
      tags:
        - Identity Providers
      parameters:
        - name: id
          in: path
          description: Identity provider ID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDPResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1002
                message: Invalid identity provider ID
                description: The provided identity provider ID is invalid or empty
        "404":
          description: "Not Found: The identity provider with the specified ID does not
            exist."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1001
                message: Identity provider not found
                description: The requested identity provider could not be found
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
    put:
      summary: Update an identity provider
      description: Update the details of an existing identity provider.
      tags:
        - Identity Providers
      parameters:
        - name: id
          in: path
          description: Identity provider ID
          required: true
          schema:
            type: string
      requestBody:
        description: Updated identity provider data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IDPRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDPResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1002
                message: Invalid identity provider ID
                description: The provided identity provider ID is invalid or empty
        "404":
          description: "Not Found: The identity provider with the specified ID does not
            exist."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1001
                message: Identity provider not found
                description: The requested identity provider could not be found
        "409":
          description: "Conflict: An identity provider with the same name already exists."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1004
                message: Identity provider already exists
                description: An identity provider with the same name already exists
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
    delete:
      summary: Delete an identity provider
      description: Delete an identity provider using its ID.
      tags:
        - Identity Providers
      parameters:
        - name: id
          in: path
          description: Identity provider ID
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          description: "Bad Request: The request body is malformed or contains invalid
            data."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: IDP-1002
                message: Invalid identity provider ID
                description: The provided identity provider ID is invalid or empty
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /notification-senders/message:
    get:
      summary: List message notification senders
      description: Retrieve a list of message notification senders.
      tags:
        - Message Senders
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageNotificationSenderList"
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
    post:
      summary: Create a new message notification sender
      description: Create a new message notification sender with the provided details.
      tags:
        - Message Senders
      requestBody:
        description: Message notification sender data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageNotificationSender"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageNotificationSenderResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: MNS-1006
                message: Invalid request format
                description: The request body is malformed or contains invalid data
        "409":
          description: "Conflict: A message notification sender with the same name already
            exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: MNS-1005
                message: Duplicate sender name
                description: A sender with the same name already exists
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /notification-senders/message/{id}:
    get:
      summary: Get a message notification sender by ID
      description: Retrieve a message notification sender by its unique identifier.
      tags:
        - Message Senders
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the message notification sender
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageNotificationSenderResponse"
        "400":
          description: "Bad Request: Invalid sender ID provided"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: MNS-1002
                message: Invalid sender ID
                description: The provided sender ID is invalid
        "404":
          description: "Not Found: The specified message notification sender does not exist"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: MNS-1001
                message: Sender not found
                description: The requested notification sender could not be found
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
    put:
      summary: Update a message notification sender
      description: Update an existing message notification sender with the provided details.
      tags:
        - Message Senders
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the message notification sender to update
          schema:
            type: string
      requestBody:
        description: Updated message notification sender data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageNotificationSender"
      responses:
        "200":
          description: Updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageNotificationSenderResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: MNS-1002
                message: Invalid sender ID
                description: The provided sender ID is invalid
        "404":
          description: "Not Found: The specified message notification sender does not exist"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: MNS-1001
                message: Sender not found
                description: The requested notification sender could not be found
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
    delete:
      summary: Delete a message notification sender
      description: Delete a message notification sender using its unique identifier.
      tags:
        - Message Senders
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the message notification sender to delete
          schema:
            type: string
      responses:
        "204":
          description: No Content - Successfully deleted the message notification sender
        "400":
          description: "Bad Request: Invalid sender ID provided"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: MNS-1002
                message: Invalid sender ID
                description: The provided sender ID is invalid
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /notification-senders/otp/send:
    post:
      summary: Send a One Time Password (OTP)
      description: Send a One Time Password (OTP) to a recipient using a specified
        message notification sender.
      tags:
        - One Time Password (OTP)
      requestBody:
        description: OTP send request data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient:
                  type: string
                  description: Recipient's mobile number
                  example: "+1234567890"
                senderId:
                  type: string
                  description: ID of the message notification sender to use
                  example: 550e8400-e29b-41d4-a716-446655440000
                channel:
                  type: string
                  description: Channel to send the OTP
                  enum:
                    - sms
                  example: sms
      responses:
        "200":
          description: OTP sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the OTP send request
                    example: SUCCESS
                  sessionToken:
                    type: string
                    description: JWT token for the OTP session
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
        "404":
          description: "Not Found: The specified message notification sender does not exist"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /notification-senders/otp/verify:
    post:
      summary: Verify a One Time Password (OTP)
      description: Verify a One Time Password (OTP) using the provided session token
        and OTP code.
      tags:
        - One Time Password (OTP)
      requestBody:
        description: OTP verify request data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionToken:
                  type: string
                  description: JWT token for the OTP session
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                otpCode:
                  type: string
                  description: The OTP code received by the user
                  example: "123456"
      responses:
        "200":
          description: OTP verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the OTP verification
                    example: VERIFIED
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
  /organization-units:
    get:
      tags:
        - organization-units
      summary: List root organization units
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of root organization units
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnitListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                organizationUnits:
                  - id: afc77cfd-620b-4cf0-a31c-7377b0ea8902
                    handle: engineering
                    name: Engineering
                    description: Engineering Unit
                    logoUrl: https://example.com/logos/engineering.png
                  - id: b7c40de6-95cd-4c45-8725-9c7cb5b9cafd
                    handle: sales
                    name: Sales
                    description: Sales Unit
                    logoUrl: https://example.com/logos/sales.png
                links:
                  - href: organization-units?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: OU-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: OU-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "500":
          description: Internal server error
    post:
      tags:
        - organization-units
      summary: Create a new organization unit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrganizationUnitRequest"
            examples:
              root-ou:
                summary: Root organization unit
                value:
                  handle: engineering
                  name: Engineering
                  description: Engineering Unit
                  parent: null
              nested-ou:
                summary: Nested organization unit
                value:
                  handle: frontend
                  name: Frontend Team
                  description: Handles UI/UX work
                  parent: afc77cfd-620b-4cf0-a31c-7377b0ea8902
      responses:
        "201":
          description: Organization unit created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnit"
              examples:
                root-ou:
                  summary: Root organization unit
                  value:
                    id: afc77cfd-620b-4cf0-a31c-7377b0ea8902
                    handle: engineering
                    name: Engineering
                    description: Engineering Unit
                    parent: null
                nested-ou:
                  summary: Nested organization unit
                  value:
                    id: 4d4cb83a-9bb8-4fd7-970e-36b65f9c8ea4
                    handle: frontend
                    name: Frontend Team
                    description: Handles UI/UX work
                    parent: afc77cfd-620b-4cf0-a31c-7377b0ea8902
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request:
                  summary: Invalid request format
                  value:
                    code: OU-1001
                    message: Invalid request format
                    description: The request body is malformed, contains invalid data, or required
                      fields are missing/empty
                parent-not-found:
                  summary: Parent organization unit not found
                  value:
                    code: OU-1005
                    message: Parent organization unit not found
                    description: Parent organization unit not found
                circular-dependency:
                  summary: Circular dependency detected
                  value:
                    code: OU-1007
                    message: Circular dependency detected
                    description: Setting this parent would create a circular dependency
        "409":
          description: Organization unit name conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1004
                message: Organization unit name conflict
                description: An organization unit with the same name exists under the same
                  parent
        "500":
          description: Internal server error
  /organization-units/{id}:
    get:
      tags:
        - organization-units
      summary: Get an organization unit by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Organization unit details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnit"
              example:
                id: afc77cfd-620b-4cf0-a31c-7377b0ea8902
                handle: engineering
                name: Engineering Team
                description: Engineering unit that handles all engineering tasks
                parent: null
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1003
                message: Organization unit not found
                description: The organization unit with the specified id does not exist
        "500":
          description: Internal server error
    put:
      tags:
        - organization-units
      summary: Update an organization unit by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateOrganizationUnitRequest"
            example:
              handle: engineering
              name: Engineering Team
              description: Engineering unit that handles all engineering tasks
              parent: null
      responses:
        "200":
          description: Organization unit updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnit"
              example:
                id: afc77cfd-620b-4cf0-a31c-7377b0ea8902
                handle: engineering
                name: Engineering Team
                description: Engineering unit that handles all engineering tasks
                parent: null
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request:
                  summary: Invalid request format
                  value:
                    code: OU-1001
                    message: Invalid request format
                    description: The request body is malformed, contains invalid data, or required
                      fields are missing/empty
                parent-not-found:
                  summary: Parent organization unit not found
                  value:
                    code: OU-1005
                    message: Parent organization unit not found
                    description: Parent organization unit not found
                circular-dependency:
                  summary: Circular dependency detected
                  value:
                    code: OU-1007
                    message: Circular dependency detected
                    description: Setting this parent would create a circular dependency
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1003
                message: Organization unit not found
                description: The organization unit with the specified id does not exist
        "409":
          description: Organization unit name conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1004
                message: Organization unit name conflict
                description: An organization unit with the same name exists under the same
                  parent
        "500":
          description: Internal server error
    delete:
      tags:
        - organization-units
      summary: Delete an organization unit by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Organization unit deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                has-children:
                  summary: Organization unit has children
                  value:
                    code: OU-1006
                    message: Organization unit has sub resources
                    description: Cannot delete organization unit with children or users or groups
        "500":
          description: Internal server error
  /organization-units/{id}/ous:
    get:
      tags:
        - organization-units
      summary: List child organization units
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of child organization units
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnitListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                organizationUnits:
                  - id: 6b59f277-fd79-40b1-afca-dce75d3709f7
                    name: Frontend Team
                    handle: frontend
                    description: Handles UI/UX work
                    logoUrl: https://example.com/logos/frontend.png
                  - id: 2a8f9e1c-4d7b-4c8a-9f3e-1b2c3d4e5f6g
                    name: Backend Team
                    handle: backend
                    description: Handles server-side development
                    logoUrl: null
                links:
                  - href: organization-units/afc77cfd-620b-4cf0-a31c-7377b0ea8902/ous?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: OU-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: OU-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1003
                message: Organization unit not found
                description: The organization unit with the specified id does not exist
        "500":
          description: Internal server error
  /organization-units/{id}/users:
    get:
      tags:
        - organization-units
      summary: List users in organization unit
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: List of users in the organization unit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                users:
                  - id: 3f9d5c8e-3c56-4f09-a1db-bb3d5e3f4b5d
                    display: John Doe
                  - id: 9f4bc2ee-8d1e-4e21-a3b4-17d9b612e320
                    display: Jane Smith
                links:
                  - href: organization-units/afc77cfd-620b-4cf0-a31c-7377b0ea8902/users?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: OU-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: OU-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1003
                message: Organization unit not found
                description: The organization unit with the specified id does not exist
        "500":
          description: Internal server error
  /organization-units/{id}/groups:
    get:
      tags:
        - organization-units
      summary: List groups in organization unit
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeGroupQueryParam"
      responses:
        "200":
          description: List of groups in the organization unit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                groups:
                  - id: c2a4f62d-7c79-46f2-b2de-8e8cb4f1c456
                    name: Developers
                  - id: 8a8e4fa2-2e55-478d-bf0f-4a2ddaf9ee7d
                    name: Architects
                links:
                  - href: organization-units/afc77cfd-620b-4cf0-a31c-7377b0ea8902/groups?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: OU-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: OU-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1003
                message: Organization unit not found
                description: The organization unit with the specified id does not exist
        "500":
          description: Internal server error
  /organization-units/tree/{path}:
    get:
      tags:
        - organization-units-by-path
      summary: Get an organization unit by hierarchical handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Gets the root OU with handle "engineering"

            - `engineering/frontend` - Gets the "frontend" OU under
            "engineering"

            - `engineering/frontend/ui` - Gets the "ui" OU under
            "engineering/frontend"
          example: engineering/frontend
      responses:
        "200":
          description: Organization unit details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnit"
              examples:
                single-level:
                  summary: Single level handle
                  value:
                    id: afc77cfd-620b-4cf0-a31c-7377b0ea8902
                    name: Engineering
                    handle: engineering
                    description: Engineering unit
                    parent: null
                multi-level:
                  summary: Multi-level handle path
                  value:
                    id: 6b59f277-fd79-40b1-afca-dce75d3709f7
                    name: Frontend Team
                    handle: frontend
                    description: Handles UI/UX work
                    parent: afc77cfd-620b-4cf0-a31c-7377b0ea8902
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: OU-1003
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: OU-1008
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "500":
          description: Internal server error
    put:
      tags:
        - organization-units-by-path
      summary: Update an organization unit by hierarchical handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Updates the root OU with handle "engineering"

            - `engineering/frontend` - Updates the "frontend" OU under
            "engineering"

            - `engineering/frontend/ui` - Updates the "ui" OU under
            "engineering/frontend"
          example: engineering/frontend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateOrganizationUnitByHandleRequest"
            examples:
              single-level:
                summary: Update single level OU
                value:
                  name: Engineering Division
                  handle: engineering
                  description: Main engineering division
              multi-level:
                summary: Update nested OU
                value:
                  name: Frontend Development
                  handle: frontend
                  description: Frontend development team with expanded scope
      responses:
        "200":
          description: Organization unit updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnit"
              examples:
                single-level:
                  summary: Updated single level OU
                  value:
                    id: afc77cfd-620b-4cf0-a31c-7377b0ea8902
                    name: Engineering Division
                    handle: engineering
                    description: Main engineering division
                    parent: null
                multi-level:
                  summary: Updated nested OU
                  value:
                    id: 6b59f277-fd79-40b1-afca-dce75d3709f7
                    name: Frontend Development
                    handle: frontend
                    description: Frontend development team with expanded scope
                    parent: afc77cfd-620b-4cf0-a31c-7377b0ea8902
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request:
                  summary: Invalid request format
                  value:
                    code: OU-1001
                    message: Invalid request format
                    description: The request body is malformed, contains invalid data, or required
                      fields are missing/empty
                handle-conflict:
                  summary: Handle already exists under parent
                  value:
                    code: OU-1010
                    message: Handle conflict
                    description: An organization unit with the same handle already exists under the
                      same parent
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: OU-1003
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: OU-1008
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "409":
          description: Organization unit name conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1004
                message: Organization unit name conflict
                description: An organization unit with the same name exists under the same
                  parent
        "500":
          description: Internal server error
    delete:
      tags:
        - organization-units-by-path
      summary: Delete an organization unit by hierarchical handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Deletes the root OU with handle "engineering"

            - `engineering/frontend` - Deletes the "frontend" OU under
            "engineering"

            - `engineering/frontend/ui` - Deletes the "ui" OU under
            "engineering/frontend"
          example: engineering/frontend
      responses:
        "204":
          description: Organization unit deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                has-children:
                  summary: Organization unit has children
                  value:
                    code: OU-1006
                    message: Organization unit has sub resources
                    description: Cannot delete organization unit with children or users or groups
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: OU-1003
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: OU-1008
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "500":
          description: Internal server error
  /organization-units/tree/{path}/ous:
    post:
      tags:
        - organization-units-by-path
      summary: Create a new organization unit under the specified handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of the parent organization unit handles separated
            by forward slashes.

            The new OU will be created as a child of the OU specified by this
            path.

            Examples:

            - `engineering` - Creates a new OU under the "engineering" OU

            - `engineering/frontend` - Creates a new OU under
            "engineering/frontend"
          example: engineering/frontend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrganizationUnitByHandleRequest"
            examples:
              simple-ou:
                summary: Create OU under single-level path
                value:
                  name: SRE Team
                  handle: sre
                  description: Maintains site reliability
              nested-ou:
                summary: Create OU under multi-level path
                value:
                  name: UI Team
                  handle: ui
                  description: Handles user interface development
      responses:
        "201":
          description: Organization unit created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnit"
              examples:
                simple-ou:
                  summary: OU created under single-level path
                  value:
                    name: SRE Team
                    handle: sre
                    description: Maintains site reliability
                    parent: 6b59f277-fd79-40b1-afca-dce75d3709f7
                nested-ou:
                  summary: OU created under multi-level path
                  value:
                    id: 8c3d2e1f-9a8b-4c5d-7e6f-1a2b3c4d5e6f
                    name: UI Team
                    handle: ui
                    description: Handles user interface development
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request:
                  summary: Invalid request format
                  value:
                    code: OU-1001
                    message: Invalid request format
                    description: The request body is malformed, contains invalid data, or required
                      fields are missing/empty
                invalid-parent-path:
                  summary: Parent path not found
                  value:
                    code: OU-1009
                    message: Parent handle path not found
                    description: The specified parent handle path does not exist
                handle-conflict:
                  summary: Handle already exists under parent
                  value:
                    code: OU-1010
                    message: Handle conflict
                    description: An organization unit with the same handle already exists under the
                      specified parent path
        "404":
          description: Parent organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: OU-1009
                message: Parent handle path not found
                description: The specified parent handle path does not exist
        "500":
          description: Internal server error
    get:
      tags:
        - organization-units-by-path
      summary: List child organization units by handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Lists children of the "engineering" OU

            - `engineering/frontend` - Lists children of "engineering/frontend"
          example: engineering/frontend
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of child organization units
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationUnitListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                organizationUnits:
                  - id: 6b59f277-fd79-40b1-afca-dce75d3709f7
                    name: Frontend Team
                    handle: frontend
                    description: Handles UI/UX work
                    logoUrl: https://example.com/logos/frontend.png
                  - id: 2a8f9e1c-4d7b-4c8a-9f3e-1b2c3d4e5f6g
                    name: Backend Team
                    handle: backend
                    description: Handles server-side development
                    logoUrl: null
                links:
                  - href: organization-units/tree/engineering/ous?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: OU-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: OU-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: OU-1003
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: OU-1008
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "500":
          description: Internal server error
  /organization-units/tree/{path}/users:
    get:
      tags:
        - organization-units-by-path
      summary: List users in organization unit by handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Lists users in the "engineering" OU

            - `engineering/frontend` - Lists users in "engineering/frontend"
          example: engineering/frontend
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: List of users in the organization unit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                users:
                  - id: 3f9d5c8e-3c56-4f09-a1db-bb3d5e3f4b5d
                    display: John Doe
                  - id: 9f4bc2ee-8d1e-4e21-a3b4-17d9b612e320
                    display: Jane Smith
                links:
                  - href: organization-units/tree/engineering/frontend/users?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: OU-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: OU-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: OU-1003
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: OU-1008
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "500":
          description: Internal server error
  /organization-units/tree/{path}/groups:
    get:
      tags:
        - organization-units-by-path
      summary: List groups in organization unit by handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Lists groups in the "engineering" OU

            - `engineering/frontend` - Lists groups in "engineering/frontend"
          example: engineering/frontend
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeGroupQueryParam"
      responses:
        "200":
          description: List of groups in the organization unit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                groups:
                  - id: c2a4f62d-7c79-46f2-b2de-8e8cb4f1c456
                    name: Developers
                  - id: 8a8e4fa2-2e55-478d-bf0f-4a2ddaf9ee7d
                    name: Architects
                links:
                  - href: organization-units/tree/engineering/frontend/groups?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: OU-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: OU-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: OU-1003
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: OU-1008
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "500":
          description: Internal server error
  /register/passkey/start:
    post:
      summary: Start Passkey credential registration
      description: Initiate Passkey credential creation for a user.
      tags:
        - Passkey / WebAuthn / FIDO2 Registration
      requestBody:
        description: Passkey credential creation initiation data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PasskeyRegistrationStartRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasskeyRegistrationStartResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1011
                message: Empty user ID
                description: The user ID is required to start registration
        "404":
          description: "Not Found: The user could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1008
                message: User not found
                description: No user found with the provided User ID
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /register/passkey/finish:
    post:
      summary: Finish Passkey credential registration
      description: Complete Passkey credential creation for a user.
      tags:
        - Passkey / WebAuthn / FIDO2 Registration
      requestBody:
        description: Passkey credential creation completion data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PasskeyRegistrationFinishRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasskeyRegistrationFinishResponse"
        "400":
          description: "Bad Request: The request body is malformed or contains invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              examples:
                emptyCredentialId:
                  value:
                    code: AUTHN-1012
                    message: Empty credential ID
                    description: The credential ID is required to complete registration
                emptyCredentialType:
                  value:
                    code: AUTHN-1013
                    message: Empty credential type
                    description: The credential type is required to complete registration
                invalidAttestationResponse:
                  value:
                    code: AUTHN-1015
                    message: Invalid attestation response
                    description: The attestation response is missing required fields (clientDataJSON
                      or attestationObject)
                emptySessionToken:
                  value:
                    code: AUTHN-1004
                    message: Empty session token
                    description: The provided session token is empty
        "401":
          description: "Unauthorized: Passkey registration verification failed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: PASS-1009
                message: Invalid attestation
                description: The Passkey attestation verification failed
        "404":
          description: "Not Found: The user could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientErrorResponse"
              example:
                code: AUTHN-1008
                message: User not found
                description: No user found for the provided session
        "500":
          description: "Internal Server Error: An unexpected error occurred while
            processing the request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerErrorResponse"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers:
    get:
      tags:
        - resource-servers
      summary: List resource servers
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of resource servers
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceServerListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                resourceServers:
                  - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    name: Booking System
                    description: Handles all booking operations
                    identifier: booking-system
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                    delimiter: ":"
                  - id: 257e528f-eb24-48b6-884d-20460e190957
                    name: Property Management
                    description: Property and facility management
                    identifier: property-mgmt
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                    delimiter: ":"
                links:
                  - href: resource-servers?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: RES-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: RES-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    post:
      tags:
        - resource-servers
      summary: Create a new resource server
      description: Creates a new resource server with the specified details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResourceServerRequest"
            example:
              name: Booking System
              description: Handles all booking operations
              identifier: booking-system
              ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
      responses:
        "201":
          description: Resource server created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceServer"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Booking System
                description: Handles all booking operations
                identifier: booking-system
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                delimiter: ":"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: RES-1010
                    message: Organization unit not found
                    description: The specified organization unit does not exist
                invalid-delimiter:
                  summary: Invalid delimiter
                  value:
                    code: RES-1015
                    message: Invalid delimiter
                    description: "Delimiter must be a single character from: a-z A-Z 0-9 . _ : - /"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                name-conflict:
                  summary: Name conflict
                  value:
                    code: RES-1004
                    message: Name conflict
                    description: A resource server with the same name already exists
                identifier-conflict:
                  summary: Identifier conflict
                  value:
                    code: RES-1013
                    message: Identifier conflict
                    description: A resource server with the same identifier already exists
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers/{id}:
    get:
      tags:
        - resource-servers
      summary: Get resource server details
      description: Returns resource server metadata
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Resource server details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceServer"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Booking System
                description: Handles all booking operations
                identifier: booking-system
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                delimiter: ":"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1002
                message: Invalid request format
                description: Resource server ID is required
        "404":
          description: Resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1003
                message: Resource server not found
                description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    put:
      tags:
        - resource-servers
      summary: Update resource server
      description: Updates resource server name, description, identifier, and
        organization unit.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateResourceServerRequest"
            example:
              name: Booking System Updated
              description: Updated description for booking operations
              identifier: booking-system-v2
              ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
      responses:
        "200":
          description: Resource server updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceServer"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Booking System Updated
                description: Updated description for booking operations
                identifier: booking-system-v2
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                delimiter: ":"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-id:
                  summary: Missing resource server ID
                  value:
                    code: RES-1002
                    message: Invalid request format
                    description: Resource server ID is required
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: RES-1010
                    message: Organization unit not found
                    description: The specified organization unit does not exist
        "404":
          description: Resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1003
                message: Resource server not found
                description: The resource server with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                name-conflict:
                  summary: Name conflict
                  value:
                    code: RES-1004
                    message: Name conflict
                    description: A resource server with the same name already exists
                identifier-conflict:
                  summary: Identifier conflict
                  value:
                    code: RES-1013
                    message: Identifier conflict
                    description: A resource server with the same identifier already exists
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    delete:
      tags:
        - resource-servers
      summary: Delete a resource server by id
      description: Deletes a resource server. Cannot delete if it has resources or actions.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Resource server deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-id:
                  summary: Missing resource server ID
                  value:
                    code: RES-1002
                    message: Invalid request format
                    description: Resource server ID is required
                cannot-delete:
                  summary: Cannot delete resource server
                  value:
                    code: RES-1006
                    message: Cannot delete resource server
                    description: Cannot delete resource server that has resources or actions
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers/{rsId}/resources:
    get:
      tags:
        - resources
      summary: List resources in resource server
      description: >
        Returns a paginated list of resources. Use the parentId parameter to
        filter:

        - No parentId: returns only top-level resources (where parent is null)

        - parentId={uuid}: returns direct children of specified parent
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: query
          name: parentId
          required: false
          schema:
            type: string
            format: uuid
          description: |
            Parent resource ID to filter children.
            - Omit parameter: returns only top-level resources (parent is null)
            - UUID: returns direct children of that parent
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of resources
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceListResponse"
              examples:
                top-level-only:
                  summary: Top-level resources (no parentId specified)
                  value:
                    totalResults: 3
                    startIndex: 1
                    count: 2
                    resources:
                      - id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                        name: Reservations
                        description: Reservation management
                        handle: reservations
                        parent: null
                        permission: reservations
                      - id: 6b1e7b8d-7e19-41eb-8fa2-c0ee5bb67a94
                        name: Payments
                        description: Payment processing
                        handle: payments
                        parent: null
                        permission: payments
                    links:
                      - href: resource-servers/3fa85f64-5717-4562-b3fc-2c963f66afa6/resources?offset=2&limit=2
                        rel: next
                children-of-parent:
                  summary: Children of specific parent
                  value:
                    totalResults: 2
                    startIndex: 1
                    count: 2
                    resources:
                      - id: 8b5c2f9f-6d7a-4c71-a343-3c1bbf76fg4d
                        name: Online Booking
                        description: Online booking subsystem
                        handle: online-booking
                        parent: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                        permission: reservations:online-booking
                      - id: 7c4d5e6f-8f3a-4e93-c565-5e3ddf98hi6f
                        name: Phone Booking
                        description: Phone-based booking
                        handle: phone-booking
                        parent: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                        permission: reservations:phone-booking
                    links: []
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: RES-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: RES-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1003
                message: Resource server not found
                description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    post:
      tags:
        - resources
      summary: Create a new resource
      description: >
        Creates a new resource within the resource server. Handle is immutable
        and used for permissions. Parent is immutable after creation.

        - Set parent to null for top-level resources

        - Set parent to UUID for nested resources
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResourceRequest"
            examples:
              top-level-resource:
                summary: Top-level resource
                value:
                  name: Reservations
                  description: Reservation management
                  handle: reservations
                  parent: null
              nested-resource:
                summary: Nested resource
                value:
                  name: Online Booking
                  description: Online booking subsystem
                  handle: online-booking
                  parent: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
      responses:
        "201":
          description: Resource created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
              examples:
                top-level-resource:
                  summary: Top-level resource created
                  value:
                    id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                    name: Reservations
                    description: Reservation management
                    handle: reservations
                    parent: null
                    permission: reservations
                nested-resource:
                  summary: Nested resource created
                  value:
                    id: 8b5c2f9f-6d7a-4c71-a343-3c1bbf76fg4d
                    name: Online Booking
                    description: Online booking subsystem
                    handle: online-booking
                    parent: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                    permission: reservations:online-booking
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                parent-not-found:
                  summary: Parent resource not found
                  value:
                    code: RES-1005
                    message: Parent resource not found
                    description: The specified parent resource does not exist
        "404":
          description: Resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1003
                message: Resource server not found
                description: The resource server with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1014
                message: Handle conflict
                description: The same handle already exists within the specified resource
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers/{rsId}/resources/{id}:
    get:
      tags:
        - resources
      summary: Get resource details
      description: Returns resource metadata
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
      responses:
        "200":
          description: Resource details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
              example:
                id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                name: Reservations
                description: Reservation management
                handle: reservations
                parent: null
                permission: reservations
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1002
                message: Invalid request format
                description: Resource ID is required
        "404":
          description: Resource or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                resource-not-found:
                  summary: Resource not found
                  value:
                    code: RES-1008
                    message: Resource not found
                    description: The resource with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    put:
      tags:
        - resources
      summary: Update resource
      description: >
        Updates resource name and description. Handle and parent are immutable
        after creation.
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateResourceRequest"
            example:
              name: Reservations Updated
              description: Updated reservation management
      responses:
        "200":
          description: Resource updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
              example:
                id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                name: Reservations Updated
                handle: reservations
                description: Updated reservation management
                parent: null
                permission: reservations
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-id:
                  summary: Missing resource ID
                  value:
                    code: RES-1002
                    message: Invalid request format
                    description: Resource ID is required
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
        "404":
          description: Resource or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                resource-not-found:
                  summary: Resource not found
                  value:
                    code: RES-1008
                    message: Resource not found
                    description: The resource with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    delete:
      tags:
        - resources
      summary: Delete a resource by id
      description: Deletes a resource. Cannot delete if it has sub-resources or actions.
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
      responses:
        "204":
          description: Resource deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-id:
                  summary: Missing resource ID
                  value:
                    code: RES-1002
                    message: Invalid request format
                    description: Resource ID is required
                cannot-delete:
                  summary: Cannot delete resource
                  value:
                    code: RES-1006
                    message: Cannot delete resource
                    description: Cannot delete resource that has sub-resources or actions
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers/{rsId}/actions:
    get:
      tags:
        - actions
      summary: List actions at resource server level
      description: Returns all actions defined at the resource server level
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                actions:
                  - id: 9c6d3g0g-7e8b-4d82-b454-4d2ccg87gh5e
                    name: Create Booking
                    description: Create a new booking
                    handle: create
                    permission: create
                  - id: ad7e4h1h-8f9c-4e93-c565-5e3ddf98hi6f
                    name: List Bookings
                    description: List all bookings
                    handle: list
                    permission: list
                links:
                  - href: resource-servers/3fa85f64-5717-4562-b3fc-2c963f66afa6/actions?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: RES-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: RES-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1003
                message: Resource server not found
                description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    post:
      tags:
        - actions
      summary: Create an action at resource server level
      description: Creates a new action at the resource server level. Handle is
        immutable and used for permissions.
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateActionRequest"
            example:
              name: Create Booking
              description: Create a new booking
              handle: create
      responses:
        "201":
          description: Action created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                id: 9c6d3g0g-7e8b-4d82-b454-4d2ccg87gh5e
                name: Create Booking
                description: Create a new booking
                handle: create
                permission: create
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-handle:
                  summary: Invalid handle
                  value:
                    code: RES-1016
                    message: Invalid handle
                    description: "Handle length must be less than 100 characters and contain only
                      valid characters: a-z A-Z 0-9 . _ : - /"
                delimiter-conflict:
                  summary: Delimiter conflict in handle
                  value:
                    code: RES-1017
                    message: Delimiter conflict in handle
                    description: Handle cannot contain the delimiter character
        "404":
          description: Resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1003
                message: Resource server not found
                description: The resource server with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1014
                message: Handle conflict
                description: The same handle already exists within the specified resource
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers/{rsId}/actions/{id}:
    get:
      tags:
        - actions
      summary: Get action details at resource server level
      description: Returns action metadata
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Action ID
      responses:
        "200":
          description: Action details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                id: 9c6d3g0g-7e8b-4d82-b454-4d2ccg87gh5e
                name: Create Booking
                description: Create a new booking
                handle: create
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1002
                message: Invalid request format
                description: Action ID is required
        "404":
          description: Action or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                action-not-found:
                  summary: Action not found
                  value:
                    code: RES-1009
                    message: Action not found
                    description: The action with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    put:
      tags:
        - actions
      summary: Update action at resource server level
      description: Updates action name and description. Handle is immutable after creation.
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Action ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateActionRequest"
            example:
              name: Create Booking Updated
              description: Updated description for creating bookings
      responses:
        "200":
          description: Action updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                id: 9c6d3g0g-7e8b-4d82-b454-4d2ccg87gh5e
                name: Create Booking Updated
                handle: create
                description: Updated description for creating bookings
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-id:
                  summary: Missing action ID
                  value:
                    code: RES-1002
                    message: Invalid request format
                    description: Action ID is required
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
        "404":
          description: Action or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                action-not-found:
                  summary: Action not found
                  value:
                    code: RES-1009
                    message: Action not found
                    description: The action with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    delete:
      tags:
        - actions
      summary: Delete an action at resource server level
      description: Deletes an action at the resource server level
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Action ID
      responses:
        "204":
          description: Action deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1002
                message: Invalid request format
                description: Action ID is required
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers/{rsId}/resources/{resourceId}/actions:
    get:
      tags:
        - actions
      summary: List actions at resource level
      description: Returns all actions defined for a specific resource
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionListResponse"
              example:
                totalResults: 6
                startIndex: 1
                count: 2
                actions:
                  - id: be8f5i2i-9g0d-5fa4-d676-6f4eeg09ij7g
                    name: Create Reservation
                    description: Create a new reservation
                    handle: create
                    permission: reservations:create
                  - id: cf9g6j3j-0h1e-6gb5-e787-7g5ffh10jk8h
                    name: Read Reservation
                    description: Read reservation details
                    handle: read
                    permission: reservations:read
                links:
                  - href: resource-servers/3fa85f64-5717-4562-b3fc-2c963f66afa6/resources/7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c/actions?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: RES-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: RES-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Resource or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                resource-not-found:
                  summary: Resource not found
                  value:
                    code: RES-1008
                    message: Resource not found
                    description: The resource with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    post:
      tags:
        - actions
      summary: Create an action at resource level
      description: Creates a new action for a specific resource. Handle is immutable
        and used for permissions.
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateActionRequest"
            example:
              name: Create Reservation
              description: Create a new reservation
              handle: create
      responses:
        "201":
          description: Action created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                id: be8f5i2i-9g0d-5fa4-d676-6f4eeg09ij7g
                name: Create Reservation
                description: Create a new reservation
                handle: create
                permission: reservations:create
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-handle:
                  summary: Invalid handle
                  value:
                    code: RES-1016
                    message: Invalid handle
                    description: "Handle must contain only valid characters (a-z A-Z 0-9 . _ : - /)
                      and cannot contain the delimiter character"
        "404":
          description: Resource or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                resource-not-found:
                  summary: Resource not found
                  value:
                    code: RES-1008
                    message: Resource not found
                    description: The resource with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1014
                message: Handle conflict
                description: The same handle already exists within the specified resource
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /resource-servers/{rsId}/resources/{resourceId}/actions/{id}:
    get:
      tags:
        - actions
      summary: Get action details at resource level
      description: Returns action metadata
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Action ID
      responses:
        "200":
          description: Action details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                id: be8f5i2i-9g0d-5fa4-d676-6f4eeg09ij7g
                name: Create Reservation
                description: Create a new reservation
                handle: create
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1002
                message: Invalid request format
                description: Action ID is required
        "404":
          description: Action, resource, or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                action-not-found:
                  summary: Action not found
                  value:
                    code: RES-1009
                    message: Action not found
                    description: The action with the specified id does not exist
                resource-not-found:
                  summary: Resource not found
                  value:
                    code: RES-1008
                    message: Resource not found
                    description: The resource with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    put:
      tags:
        - actions
      summary: Update action at resource level
      description: Updates action name and description. Handle is immutable after creation.
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Action ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateActionRequest"
            example:
              name: Create Reservation Updated
              description: Updated description for creating reservations
      responses:
        "200":
          description: Action updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                id: be8f5i2i-9g0d-5fa4-d676-6f4eeg09ij7g
                name: Create Reservation Updated
                handle: create
                description: Updated description for creating reservations
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-id:
                  summary: Missing action ID
                  value:
                    code: RES-1002
                    message: Invalid request format
                    description: Action ID is required
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: RES-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
        "404":
          description: Action, resource, or resource server not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                action-not-found:
                  summary: Action not found
                  value:
                    code: RES-1009
                    message: Action not found
                    description: The action with the specified id does not exist
                resource-not-found:
                  summary: Resource not found
                  value:
                    code: RES-1008
                    message: Resource not found
                    description: The resource with the specified id does not exist
                resource-server-not-found:
                  summary: Resource server not found
                  value:
                    code: RES-1003
                    message: Resource server not found
                    description: The resource server with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    delete:
      tags:
        - actions
      summary: Delete an action at resource level
      description: Deletes an action for a specific resource
      parameters:
        - in: path
          name: rsId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource server ID
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
            format: uuid
          description: Resource ID
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Action ID
      responses:
        "204":
          description: Action deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: RES-1002
                message: Invalid request format
                description: Action ID is required
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: SSE-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /roles:
    get:
      tags:
        - roles
      summary: List roles
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of roles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                roles:
                  - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    name: front-desk-agent
                    description: Front desk agent role with booking and customer management
                      permissions
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                  - id: 257e528f-eb24-48b6-884d-20460e190957
                    name: hotel-manager
                    description: Hotel manager with full property access
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                links:
                  - href: roles?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: ROL-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: ROL-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: ROL-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    post:
      tags:
        - roles
      summary: Create a new role
      description: Creates a new role with optional initial permissions and assignments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRoleRequest"
            example:
              name: front-desk-agent
              description: Front desk agent role with booking and customer management
                permissions
              ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
              permissions:
                - resourceServerId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  permissions:
                    - create_reservation
                    - view_reservation
                    - update_reservation
                    - check_in_guest
                    - check_out_guest
                - resourceServerId: 7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e
                  permissions:
                    - process_payment
                    - view_payment
                    - view_customer_profile
                    - update_customer_profile
              assignments:
                - type: user
                  id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                - type: group
                  id: 6b1e7b8d-7e19-41eb-8fa2-c0ee5bb67a94
      responses:
        "201":
          description: Role created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleWithAssignments"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: front-desk-agent
                description: Front desk agent role with booking and customer management
                  permissions
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                permissions:
                  - resourceServerId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    permissions:
                      - create_reservation
                      - view_reservation
                      - update_reservation
                      - check_in_guest
                      - check_out_guest
                  - resourceServerId: 7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e
                    permissions:
                      - process_payment
                      - view_payment
                      - view_customer_profile
                      - update_customer_profile
                assignments:
                  - type: user
                    id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                    display: John Doe
                  - type: group
                    id: 6b1e7b8d-7e19-41eb-8fa2-c0ee5bb67a94
                    display: Front Desk Team
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: ROL-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-assignment-id:
                  summary: Invalid assignment ID
                  value:
                    code: ROL-1007
                    message: Invalid assignment ID
                    description: One or more assignment IDs in the request do not exist
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: ROL-1005
                    message: Organization unit not found
                    description: Organization unit not found
                invalid-permissions:
                  summary: Invalid permissions
                  value:
                    code: ROL-1012
                    message: Invalid permissions
                    description: One or more permissions do not exist in the resource management
                      system
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1004
                message: Role name conflict
                description: A role with the same name exists under the same organization unit
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /roles/{id}:
    get:
      tags:
        - roles
      summary: Get role details
      description: Returns role metadata with permissions list
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Role details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: front-desk-agent
                description: Front desk agent role with booking and customer management
                  permissions
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                permissions:
                  - create_reservation
                  - view_reservation
                  - process_payment
                  - view_customer_profile
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1002
                message: Invalid request format
                description: Role ID is required
        "404":
          description: Role not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1003
                message: Role not found
                description: The role with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    put:
      tags:
        - roles
      summary: Update role
      description: Updates role name, description, organization unit, and permissions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRoleRequest"
            example:
              name: senior-front-desk-agent
              description: Senior front desk agent with additional permissions
              ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
              permissions:
                - resourceServerId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  permissions:
                    - create_reservation
                    - view_reservation
                    - update_reservation
                    - cancel_reservation
                - resourceServerId: 7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e
                  permissions:
                    - process_payment
                    - view_payment
                    - refund_payment
                    - view_customer_profile
                    - update_customer_profile
      responses:
        "200":
          description: Role updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: senior-front-desk-agent
                description: Senior front desk agent with additional permissions
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                permissions:
                  - resourceServerId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    permissions:
                      - create_reservation
                      - view_reservation
                      - update_reservation
                      - cancel_reservation
                  - resourceServerId: 7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e
                    permissions:
                      - process_payment
                      - view_payment
                      - refund_payment
                      - view_customer_profile
                      - update_customer_profile
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-role-id:
                  summary: Missing role ID
                  value:
                    code: ROL-1002
                    message: Invalid request format
                    description: Role ID is required
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: ROL-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: ROL-1005
                    message: Organization unit not found
                    description: Organization unit not found
                invalid-permissions:
                  summary: Invalid permissions
                  value:
                    code: ROL-1012
                    message: Invalid permissions
                    description: One or more permissions do not exist in the resource management
                      system
        "404":
          description: Role not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1003
                message: Role not found
                description: The role with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1004
                message: Role name conflict
                description: A role with the same name exists under the same organization unit
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    delete:
      tags:
        - roles
      summary: Delete a role by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Role deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-role-id:
                  summary: Missing role ID
                  value:
                    code: ROL-1002
                    message: Invalid request format
                    description: Role ID is required
                cannot-delete-role:
                  summary: Cannot delete role
                  value:
                    code: ROL-1006
                    message: Cannot delete role
                    description: Cannot delete role that is currently assigned to users or groups
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /roles/{id}/assignments:
    get:
      tags:
        - roles
      summary: Get role assignments
      description: Returns user and group assignments for the role. Use type to filter
        by assignee type and include=display to get display names.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/assigneeTypeQueryParam"
        - $ref: "#/components/parameters/includeQueryParam"
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of assignments
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssignmentListResponse"
              examples:
                without-display:
                  summary: Without include parameter (IDs and types only)
                  value:
                    totalResults: 5
                    startIndex: 1
                    count: 2
                    assignments:
                      - type: user
                        id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                      - type: group
                        id: 8c2f8e9e-8f2a-4f5b-9c3d-4e5f6a7b8c9d
                    links:
                      - href: roles/3fa85f64-5717-4562-b3fc-2c963f66afa6/assignments?offset=2&limit=2
                        rel: next
                with-display:
                  summary: With include=display parameter
                  value:
                    totalResults: 5
                    startIndex: 1
                    count: 2
                    assignments:
                      - type: user
                        id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                        display: John Doe
                      - type: group
                        id: 8c2f8e9e-8f2a-4f5b-9c3d-4e5f6a7b8c9d
                        display: Front Desk Team
                    links:
                      - href: roles/3fa85f64-5717-4562-b3fc-2c963f66afa6/assignments?offset=2&limit=2
                        rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-type:
                  summary: Invalid assignee type parameter
                  value:
                    code: ROL-1017
                    message: Invalid assignee type
                    description: The type parameter must be either 'user' or 'group'
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: ROL-1011
                    message: Invalid limit parameter
                    description: The limit parameter must be a positive integer
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: ROL-1012
                    message: Invalid offset parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: Role not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1003
                message: Role not found
                description: The role with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /roles/{id}/assignments/add:
    post:
      tags:
        - roles
      summary: Add assignments to a role
      description: Adds one or more user or group assignments to the specified role
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssignmentsRequest"
            example:
              assignments:
                - type: user
                  id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                - type: group
                  id: 6b1e7b8d-7e19-41eb-8fa2-c0ee5bb67a94
      responses:
        "204":
          description: Assignments added successfully
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: ROL-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-assignment-id:
                  summary: Invalid assignment ID
                  value:
                    code: ROL-1007
                    message: Invalid assignment ID
                    description: One or more assignment IDs in the request do not exist
                empty-assignments:
                  summary: Empty assignments
                  value:
                    code: ROL-1014
                    message: Empty assignments list
                    description: At least one assignment must be provided
        "404":
          description: Role not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1003
                message: Role not found
                description: The role with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /roles/{id}/assignments/remove:
    post:
      tags:
        - roles
      summary: Remove assignments from a role
      description: Removes one or more user or group assignments from the specified role
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssignmentsRequest"
            example:
              assignments:
                - type: user
                  id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                - type: group
                  id: 6b1e7b8d-7e19-41eb-8fa2-c0ee5bb67a94
      responses:
        "204":
          description: Assignments removed successfully
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: ROL-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                empty-assignments:
                  summary: Empty assignments
                  value:
                    code: ROL-1014
                    message: Empty assignments list
                    description: At least one assignment must be provided
        "404":
          description: Role not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-1003
                message: Role not found
                description: The role with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: ROL-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /users:
    get:
      tags:
        - users
      summary: List users
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/filterParam"
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 3
                users:
                  - id: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
                    ouId: 456e8400-e29b-41d4-a716-446655440001
                    type: customer
                    attributes:
                      age: 24
                      email: jane.doe@example.com
                      mobile: +1-650-555-1234
                      address:
                        city: Mountain View
                        zip: "94040"
                      contactPreferences:
                        - email
                        - sms
                  - id: 039bda67-a80d-4b7b-ac0f-36db85332089
                    ouId: 456e8400-e29b-41d4-a716-446655440001
                    type: customer
                    attributes:
                      age: 31
                      email: john.smith@example.com
                      mobile: +1-650-903-0002
                      address:
                        city: Palo Alto
                        zip: "94301"
                      contactPreferences:
                        - sms
                  - id: e1b6ba6c-deb2-4d24-87b0-bbf79fa4487c
                    ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
                    type: employee
                    attributes:
                      username: alice.wu
                      firstname: Alice
                      lastname: Wu
                      department: Engineering
                      email: alice.wu@company.inc
                links:
                  - href: users?offset=3&limit=3
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: USR-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be between 1 and 100
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: USR-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
                invalid-filter:
                  summary: Invalid filter parameter
                  value:
                    code: USR-1020
                    message: Invalid filter parameter
                    description: The filter format is invalid
        "500":
          description: Internal server error
    post:
      tags:
        - users
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
            example:
              ouId: 456e8400-e29b-41d4-a716-446655440001
              type: customer
              groups:
                - 550e8400-e29b-41d4-a716-446655440000
                - 660e8400-e29b-41d4-a716-446655440001
              attributes:
                age: 24
                email: jane.doe@example.com
                mobile: +1-650-555-1234
                address:
                  city: Mountain View
                  zip: "94040"
                contactPreferences:
                  - email
                  - sms
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                id: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
                ouId: 456e8400-e29b-41d4-a716-446655440001
                type: customer
                attributes:
                  age: 24
                  email: jane.doe@example.com
                  mobile: +1-650-555-1234
                  address:
                    city: Mountain View
                    zip: "94040"
                  contactPreferences:
                    - email
                    - sms
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: USR-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-group-id:
                  summary: Invalid group ID
                  value:
                    code: USR-1007
                    message: Invalid group ID
                    description: One or more group IDs in the request do not exist
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: USR-1005
                    message: Organization unit not found
                    description: The specified organization unit does not exist
                schema-validation-failed:
                  summary: Schema validation failed
                  value:
                    code: USR-1019
                    message: Schema validation failed
                    description: User attributes do not conform to the required schema
                user-schema-not-found:
                  summary: User schema not found
                  value:
                    code: USR-1021
                    message: User schema not found
                    description: The specified user schema does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                attribute-conflict:
                  summary: Unique attribute conflict
                  value:
                    code: USR-1014
                    message: Attribute conflict
                    description: A user with the same unique attribute value already exists
        "500":
          description: Internal server error
  /users/{id}:
    get:
      tags:
        - users
      summary: Get a user by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          example: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                id: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
                ouId: 456e8400-e29b-41d4-a716-446655440001
                type: customer
                attributes:
                  age: 24
                  email: jane.doe@example.com
                  mobile: +1-650-555-1234
                  address:
                    city: Mountain View
                    zip: "94040"
                  contactPreferences:
                    - email
                    - sms
        "404":
          description: User not found
        "500":
          description: Internal server error
    put:
      tags:
        - users
      summary: Update a user by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          example: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
            example:
              ouId: 456e8400-e29b-41d4-a716-446655440001
              type: customer
              groups:
                - 550e8400-e29b-41d4-a716-446655440000
              attributes:
                age: 25
                email: jane.doe@example.com
                mobile: +1-650-555-5678
                address:
                  city: Mountain View
                  zip: "94040"
                contactPreferences:
                  - email
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                id: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
                ouId: 456e8400-e29b-41d4-a716-446655440001
                type: customer
                attributes:
                  age: 25
                  email: jane.doe@example.com
                  mobile: +1-650-555-5678
                  address:
                    city: Mountain View
                    zip: "94040"
                  contactPreferences:
                    - email
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: USR-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-group-id:
                  summary: Invalid group ID
                  value:
                    code: USR-1007
                    message: Invalid group ID
                    description: One or more group IDs in the request do not exist
                ou-not-found:
                  summary: Organization unit not found
                  value:
                    code: USR-1005
                    message: Organization unit not found
                    description: The specified organization unit does not exist
                schema-validation-failed:
                  summary: Schema validation failed
                  value:
                    code: USR-1019
                    message: Schema validation failed
                    description: User attributes do not conform to the required schema
                user-schema-not-found:
                  summary: User schema not found
                  value:
                    code: USR-1021
                    message: User schema not found
                    description: The specified user schema does not exist
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1003
                message: User not found
                description: The user with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                attribute-conflict:
                  summary: Unique attribute conflict
                  value:
                    code: USR-1014
                    message: Attribute conflict
                    description: A user with the same unique attribute value already exists
        "500":
          description: Internal server error
    delete:
      tags:
        - users
      summary: Delete a user by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          example: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
      responses:
        "204":
          description: User deleted
        "404":
          description: User not found
        "500":
          description: Internal server error
  /users/{id}/groups:
    get:
      tags:
        - users
      summary: List groups that the user belongs to
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: The unique identifier of the user
          example: 9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
      responses:
        "200":
          description: List of groups that the user belongs to
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserGroupListResponse"
              example:
                totalResults: 3
                startIndex: 1
                count: 2
                groups:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    name: Premium Customers
                    ouId: 456e8400-e29b-41d4-a716-446655440001
                  - id: 660e8400-e29b-41d4-a716-446655440001
                    name: Mobile App Users
                    ouId: 456e8400-e29b-41d4-a716-446655440001
                links:
                  - href: users/9a475e1e-b0cb-4b29-8df5-2e5b24fb0ed3/groups?offset=2&limit=2
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-user-id:
                  summary: Missing user ID
                  value:
                    code: USR-1002
                    message: Invalid request format
                    description: User ID is required
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: USR-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be between 1 and 100
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: USR-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1003
                message: User not found
                description: The user with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /users/tree/{path}:
    get:
      tags:
        - users-by-path
      summary: List users in organization unit specified by handle path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            Examples:

            - `engineering` - Lists users in the "engineering" OU

            - `engineering/frontend` - Lists users in "engineering/frontend"
          example: engineering/frontend
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/filterParam"
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: List of users in the organization unit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
              example:
                totalResults: 5
                startIndex: 1
                count: 2
                users:
                  - id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                  - id: 9f1e47d3-0347-4464-9f02-e0bfae02e896
                links:
                  - href: users/tree/engineering/frontend?offset=10&limit=10
                    rel: next
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: USR-1011
                    message: Invalid pagination parameter
                    description: The limit parameter must be between 1 and 100
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: USR-1012
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
                invalid-filter:
                  summary: Invalid filter parameter
                  value:
                    code: USR-1020
                    message: Invalid filter parameter
                    description: The filter format is invalid
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: USR-1005
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: USR-1009
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
    post:
      tags:
        - users-by-path
      summary: Create a new user under the organization unit specified by the handle
        path
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          style: simple
          explode: false
          description: >
            Hierarchical path of organization unit handles separated by forward
            slashes.

            The new user will be created under the organization unit specified
            by this path.

            Examples:

            - `engineering` - Creates a new user under the "engineering" OU

            - `engineering/frontend` - Creates a new user under
            "engineering/frontend"
          example: engineering/frontend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserByPathRequest"
            example:
              type: employee
              groups:
                - 880e8400-e29b-41d4-a716-446655440003
                - 990e8400-e29b-41d4-a716-446655440004
              attributes:
                username: john.doe
                firstname: John
                lastname: Doe
                email: john.doe@company.com
                department: Engineering
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                id: 7a4b1f8e-5c69-4b60-9232-2b0aaf65ef3c
                ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                type: employee
                attributes:
                  username: john.doe
                  firstname: John
                  lastname: Doe
                  email: john.doe@company.com
                  department: Engineering
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: USR-1001
                    message: Invalid request format
                    description: The request body is malformed, contains invalid data, or required
                      fields are missing/empty
                invalid-group-id:
                  summary: Invalid group ID
                  value:
                    code: USR-1007
                    message: Invalid group ID
                    description: One or more group IDs in the request do not exist
                schema-validation-failed:
                  summary: Schema validation failed
                  value:
                    code: USR-1019
                    message: Schema validation failed
                    description: User attributes do not conform to the required schema
                user-schema-not-found:
                  summary: User schema not found
                  value:
                    code: USR-1021
                    message: User schema not found
                    description: The specified user schema does not exist
        "404":
          description: Organization unit not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                path-not-found:
                  summary: Handle path not found
                  value:
                    code: USR-1005
                    message: Organization unit not found
                    description: The organization unit with the specified handle path does not exist
                invalid-path:
                  summary: Invalid path structure
                  value:
                    code: USR-1009
                    message: Invalid handle path
                    description: The handle path does not represent a valid organizational hierarchy
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                username-conflict:
                  summary: Unique attribute conflict
                  value:
                    code: USR-1014
                    message: Attribute conflict
                    description: A user with the same unique attribute value already exists
                email-conflict:
                  summary: Email already exists
                  value:
                    code: USR-1015
                    message: Email conflict
                    description: A user with the same email already exists
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
              example: Internal server error
  /users/me:
    get:
      tags:
        - self
      summary: Get self user profile
      security:
        - OAuth2: []
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                id: e1b6ba6c-deb2-4d24-87b0-bbf79fa4487c
                ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
                type: employee
                attributes:
                  username: alice.wu
                  firstname: Alice
                  lastname: Wu
                  email: alice.wu@company.inc
        "401":
          description: Unauthorized - missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1018
                message: Authentication failed
                description: Invalid credentials provided
        "404":
          description: Authenticated user not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1003
                message: User not found
                description: The user with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
    put:
      tags:
        - self
      summary: Update self user profile
      security:
        - OAuth2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSelfUserRequest"
            example:
              attributes:
                username: alice.wu
                firstname: Alice
                lastname: Wu
                email: alice.wu@company.io
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                id: e1b6ba6c-deb2-4d24-87b0-bbf79fa4487c
                ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
                type: employee
                attributes:
                  username: alice.wu
                  firstname: Alice
                  lastname: Wu
                  email: alice.wu@company.io
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: USR-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                schema-validation-failed:
                  summary: Schema validation failed
                  value:
                    code: USR-1019
                    message: Schema validation failed
                    description: User attributes do not conform to the required schema
                user-schema-not-found:
                  summary: User schema not found
                  value:
                    code: USR-1021
                    message: User schema not found
                    description: The specified user schema does not exist
        "401":
          description: Unauthorized - missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1018
                message: Authentication failed
                description: Invalid credentials provided
        "404":
          description: Authenticated user not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1003
                message: User not found
                description: The user with the specified id does not exist
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1014
                message: Attribute conflict
                description: A user with the same unique attribute value already exists
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /users/me/update-credentials:
    post:
      tags:
        - self
      summary: Update self user credentials
      security:
        - OAuth2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSelfUserRequest"
            example:
              attributes:
                password: n3wP@ssword!
      responses:
        "204":
          description: Credentials updated
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing-credentials:
                  summary: Missing credentials
                  value:
                    code: USR-1017
                    message: Missing credentials
                    description: At least one credential field must be provided
        "401":
          description: Unauthorized - missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1018
                message: Authentication failed
                description: Invalid credentials provided
        "404":
          description: Authenticated user not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-1003
                message: User not found
                description: The user with the specified id does not exist
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USR-5000
                message: Internal server error
                description: An unexpected error occurred while processing the request
  /user-schemas:
    get:
      tags:
        - user-schemas
      summary: List user type schemas
      description: |
        Retrieves a list of all user type schemas that define the structure
        and attributes for different user types.
      parameters:
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/offsetQueryParam"
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: List of user type schemas
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSchemaListResponse"
              example:
                totalResults: 3
                startIndex: 1
                count: 3
                schemas:
                  - id: 660e8400-e29b-41d4-a716-446655440001
                    name: employee
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                    allowSelfRegistration: false
                    systemAttributes:
                      display: username
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    name: customer
                    ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
                    allowSelfRegistration: true
                    systemAttributes:
                      display: email
                  - id: 770e8400-e29b-41d4-a716-446655440002
                    name: partner
                    ouId: 770e8400-e29b-41d4-a716-446655440002
                    allowSelfRegistration: false
                    systemAttributes:
                      display: email
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-limit:
                  summary: Invalid limit parameter
                  value:
                    code: USRS-1005
                    message: Invalid pagination parameter
                    description: The limit parameter must be between 1 and 100
                invalid-offset:
                  summary: Invalid offset parameter
                  value:
                    code: USRS-1006
                    message: Invalid pagination parameter
                    description: The offset parameter must be a non-negative integer
        "500":
          description: Internal server error
    post:
      tags:
        - user-schemas
      summary: Create a new user type schema
      description: |
        Creates a new user type schema that defines the structure and attributes
        for a specific user type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserSchemaRequest"
            example:
              name: partner
              ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
              allowSelfRegistration: false
              systemAttributes:
                display: email
              schema:
                firstname:
                  type: string
                lastname:
                  type: string
                  required: true
                email:
                  type: string
                  required: true
                  unique: true
                password:
                  type: string
                  required: true
                  credential: true
                company:
                  type: string
                role:
                  type: string
                partnershipType:
                  type: string
                  enum:
                    - technology
                    - business
                    - strategic
                phoneNumber:
                  type: string
      responses:
        "201":
          description: User schema created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSchema"
              example:
                id: 880e8400-e29b-41d4-a716-446655440003
                name: partner
                ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
                allowSelfRegistration: false
                systemAttributes:
                  display: email
                schema:
                  firstname:
                    type: string
                  lastname:
                    type: string
                    required: true
                  email:
                    type: string
                    required: true
                    unique: true
                  password:
                    type: string
                    required: true
                    credential: true
                  company:
                    type: string
                  role:
                    type: string
                  partnershipType:
                    type: string
                    enum:
                      - technology
                      - business
                      - strategic
                  phoneNumber:
                    type: string
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: USRS-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-attribute-definition:
                  summary: Invalid attribute definition
                  value:
                    code: USRS-1004
                    message: Invalid user schema request
                    description: One or more attribute definitions are invalid
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USRS-1003
                message: User schema name conflict
                description: A user schema with the same name already exists
        "500":
          description: Internal server error
  /user-schemas/{id}:
    get:
      tags:
        - user-schemas
      summary: Get a user type schema by ID
      description: |
        Retrieves the details of a specific user type schema by its ID.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        - $ref: "#/components/parameters/includeQueryParam"
      responses:
        "200":
          description: User schema details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSchema"
              examples:
                simple:
                  summary: Employee schema with simple attributes
                  value:
                    id: 660e8400-e29b-41d4-a716-446655440001
                    name: employee
                    ouId: a839f4bd-39dc-4eaa-b5cc-210d8ecaee87
                    allowSelfRegistration: false
                    systemAttributes:
                      display: username
                    schema:
                      firstname:
                        type: string
                      lastname:
                        type: string
                        required: true
                      username:
                        type: string
                        required: true
                        unique: true
                      password:
                        type: string
                        required: true
                        credential: true
                        regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]).{8,}$
                      employeeId:
                        type: number
                        unique: true
                      department:
                        type: string
                        enum:
                          - Engineering
                          - Marketing
                          - Sales
                          - HR
                          - Finance
                          - Operations
                      isActive:
                        type: boolean
                complex:
                  summary: Customer schema with complex attributes
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    name: customer
                    ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
                    allowSelfRegistration: true
                    systemAttributes:
                      display: email
                    schema:
                      email:
                        type: string
                        required: true
                        unique: true
                        regex: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
                      mobile:
                        type: string
                        regex: ^\+?[1-9]\d{1,14}$
                      address:
                        type: object
                        required: true
                        properties:
                          street:
                            type: string
                          city:
                            type: string
                            required: true
                          zipCode:
                            type: string
                            regex: ^\d{5}(-\d{4})?$
                          country:
                            type: string
                      contactPreferences:
                        type: array
                        items:
                          type: string
                          enum:
                            - email
                            - sms
                            - phone
                            - mail
        "404":
          description: User schema not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USRS-1002
                message: User schema not found
                description: The user schema with the specified id does not exist
        "500":
          description: Internal server error
    put:
      tags:
        - user-schemas
      summary: Update a user type schema by ID
      description: |
        Updates an existing user type schema with new attribute definitions.
        This operation replaces the entire schema definition.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserSchemaRequest"
            example:
              name: customer
              ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
              allowSelfRegistration: true
              systemAttributes:
                display: email
              schema:
                email:
                  type: string
                  required: true
                  unique: true
                password:
                  type: string
                  required: true
                  credential: true
                age:
                  type: number
                mobile:
                  type: string
                preferredLanguage:
                  type: string
                  enum:
                    - en
                    - es
                    - fr
                    - de
                    - it
                loyaltyTier:
                  type: string
                  enum:
                    - bronze
                    - silver
                    - gold
                    - platinum
      responses:
        "200":
          description: User schema updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSchema"
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: customer
                ouId: 26eec421-f1bb-4deb-a5d3-9ab6554c2ae6
                allowSelfRegistration: true
                systemAttributes:
                  display: email
                schema:
                  email:
                    type: string
                    required: true
                    unique: true
                  password:
                    type: string
                    required: true
                    credential: true
                  age:
                    type: number
                  mobile:
                    type: string
                  preferredLanguage:
                    type: string
                    enum:
                      - en
                      - es
                      - fr
                      - de
                      - it
                  loyaltyTier:
                    type: string
                    enum:
                      - bronze
                      - silver
                      - gold
                      - platinum
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalid-request-format:
                  summary: Invalid request format
                  value:
                    code: USRS-1001
                    message: Invalid request format
                    description: The request body is malformed or contains invalid data
                invalid-attribute-definition:
                  summary: Invalid attribute definition
                  value:
                    code: USRS-1004
                    message: Invalid user schema request
                    description: One or more attribute definitions are invalid
        "404":
          description: User schema not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USRS-1002
                message: User schema not found
                description: The user schema with the specified id does not exist
        "409":
          description: User schema name already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USRS-1003
                message: User schema name conflict
                description: A user schema with the same name already exists
        "500":
          description: Internal server error
    delete:
      tags:
        - user-schemas
      summary: Delete a user type schema by ID
      description: |
        Deletes a user type schema. This operation will fail if there are 
        existing users of this type.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        "204":
          description: User schema deleted
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: USRS-1004
                message: Invalid user schema request
                description: Cannot delete schema because users of this type exist
        "500":
          description: Internal server error
components:
  schemas:
    ApplicationRequest:
      type: object
      required:
        - name
        - ouId
      properties:
        ouId:
          type: string
          description: The ID of the organization unit this application belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The name of the application.
          example: My Web Application
        description:
          type: string
          description: A brief description of the application.
          example: Customer portal application
        authFlowId:
          type: string
          description: The ID of the authentication flow.
          example: edc013d0-e893-4dc0-990c-3e1d203e005b
        registrationFlowId:
          type: string
          description: The ID of the registration flow.
          example: 80024fb3-29ed-4c33-aa48-8aee5e96d522
        isRegistrationFlowEnabled:
          type: boolean
          description: Indicates if the registration flow is enabled for the application.
          example: true
          default: false
        themeId:
          type: string
          format: uuid
          description: The ID of the theme configuration associated with this application.
          example: 660e8400-e29b-41d4-a716-446655440001
        layoutId:
          type: string
          format: uuid
          description: The ID of the layout configuration associated with this application.
          example: 770e8400-e29b-41d4-a716-446655440002
        template:
          type: string
          description: The template type of the application.
          example: spa
        url:
          type: string
          format: uri
          description: The URL of the application.
          example: https://myapp.example.com
        logoUrl:
          type: string
          format: uri
          description: The URL of the application's logo.
          example: https://myapp.example.com/logo.png
        assertion:
          $ref: "#/components/schemas/AssertionConfig"
        certificate:
          $ref: "#/components/schemas/Certificate"
        inboundAuthConfig:
          type: array
          items:
            $ref: "#/components/schemas/InboundAuthConfigComplete"
          description: Inbound authentication configuration for the application.
        tosUri:
          type: string
          format: uri
          description: URL pointing to the Terms of Service for the application.
          example: https://myapp.example.com/terms
        policyUri:
          type: string
          format: uri
          description: URL pointing to the Privacy Policy for the application.
          example: https://myapp.example.com/privacy
        contacts:
          type: array
          items:
            type: string
            format: email
          description: Array of email addresses of people responsible for the application.
          example:
            - admin@myapp.example.com
            - support@myapp.example.com
        allowedUserTypes:
          type: array
          items:
            type: string
          description: Array of allowed user types for this application.
          example:
            - employee
            - customer
            - partner
        loginConsent:
          type: object
          properties:
            validityPeriod:
              type: integer
              description: The validity period of the login consent in seconds. Default is 0
                (no expiration).
              example: 3600
        metadata:
          type: object
          additionalProperties: true
          description: Generic metadata for the application. Arbitrary key-value pairs for
            consumer use.
          example:
            env: production
            team: platform
    ApplicationCompleteResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the application.
          example: 550e8400-e29b-41d4-a716-446655440000
        ouId:
          type: string
          description: The ID of the organization unit this application belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The name of the application.
          example: My Web Application
        description:
          type: string
          description: A brief description of the application.
          example: Customer portal application
        clientId:
          type: string
          description: The client ID for the application.
          example: myapp_client_id
        authFlowId:
          type: string
          description: The ID of the authentication flow.
          example: edc013d0-e893-4dc0-990c-3e1d203e005b
        registrationFlowId:
          type: string
          description: The ID of the registration flow.
          example: 80024fb3-29ed-4c33-aa48-8aee5e96d522
        isRegistrationFlowEnabled:
          type: boolean
          description: Indicates if the registration flow is enabled for the application.
          example: true
        themeId:
          type: string
          format: uuid
          description: The ID of the theme configuration associated with this application.
        layoutId:
          type: string
          format: uuid
          description: The ID of the layout configuration associated with this application.
          example: 660e8400-e29b-41d4-a716-446655440001
        template:
          type: string
          description: The template type of the application.
          example: spa
        url:
          type: string
          format: uri
          description: The URL of the application.
          example: https://myapp.example.com
        logoUrl:
          type: string
          format: uri
          description: The URL of the application's logo.
          example: https://myapp.example.com/logo.png
        assertion:
          $ref: "#/components/schemas/AssertionConfig"
        certificate:
          $ref: "#/components/schemas/Certificate"
        inboundAuthConfig:
          type: array
          items:
            $ref: "#/components/schemas/InboundAuthConfigComplete"
          description: Inbound authentication configuration for the application.
        tosUri:
          type: string
          format: uri
          description: URL pointing to the Terms of Service for the application.
          example: https://myapp.example.com/terms
        policyUri:
          type: string
          format: uri
          description: URL pointing to the Privacy Policy for the application.
          example: https://myapp.example.com/privacy
        contacts:
          type: array
          items:
            type: string
            format: email
          description: Array of email addresses of people responsible for the application.
          example:
            - admin@myapp.example.com
            - support@myapp.example.com
        allowedUserTypes:
          type: array
          items:
            type: string
          description: Array of allowed user types for this application.
          example:
            - employee
            - customer
            - partner
        loginConsent:
          type: object
          properties:
            validityPeriod:
              type: integer
              description: The validity period of the consent in seconds. Default is 0 (no
                expiration).
              example: 3600
        metadata:
          type: object
          additionalProperties: true
          description: Generic metadata for the application. Arbitrary key-value pairs for
            consumer use.
          example:
            env: production
            team: platform
    ApplicationGetResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the application.
          example: 550e8400-e29b-41d4-a716-446655440000
        ouId:
          type: string
          description: The ID of the organization unit this application belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The name of the application.
          example: My Web Application
        description:
          type: string
          description: A brief description of the application.
          example: Customer portal application
        clientId:
          type: string
          description: The client ID for the application.
          example: myapp_client_id
        authFlowId:
          type: string
          description: The ID of the authentication flow.
          example: edc013d0-e893-4dc0-990c-3e1d203e005b
        registrationFlowId:
          type: string
          description: The ID of the registration flow.
          example: 80024fb3-29ed-4c33-aa48-8aee5e96d522
        isRegistrationFlowEnabled:
          type: boolean
          description: Indicates if the registration flow is enabled for the application.
          example: true
        themeId:
          type: string
          format: uuid
          description: The ID of the theme configuration associated with this application.
        layoutId:
          type: string
          format: uuid
          description: The ID of the layout configuration associated with this application.
          example: 770e8400-e29b-41d4-a716-446655440002
        template:
          type: string
          description: The template type of the application.
          example: spa
        url:
          type: string
          format: uri
          description: The URL of the application.
          example: https://myapp.example.com
        logoUrl:
          type: string
          format: uri
          description: The URL of the application's logo.
          example: https://myapp.example.com/logo.png
        assertion:
          $ref: "#/components/schemas/AssertionConfig"
        certificate:
          $ref: "#/components/schemas/Certificate"
        inboundAuthConfig:
          type: array
          items:
            $ref: "#/components/schemas/InboundAuthConfig"
          description: Inbound authentication configuration for the application.
        tosUri:
          type: string
          format: uri
          description: URL pointing to the Terms of Service for the application.
          example: https://myapp.example.com/terms
        policyUri:
          type: string
          format: uri
          description: URL pointing to the Privacy Policy for the application.
          example: https://myapp.example.com/privacy
        contacts:
          type: array
          items:
            type: string
            format: email
          description: Array of email addresses of people responsible for the application.
          example:
            - admin@myapp.example.com
            - support@myapp.example.com
        allowedUserTypes:
          type: array
          items:
            type: string
          description: Array of allowed user types for this application.
          example:
            - employee
            - customer
            - partner
        loginConsent:
          type: object
          properties:
            validityPeriod:
              type: integer
              description: The validity period of the consent in seconds. Default is 0 (no
                expiration).
              example: 3600
        metadata:
          type: object
          additionalProperties: true
          description: Generic metadata for the application. Arbitrary key-value pairs for
            consumer use.
          example:
            env: production
            team: platform
    BasicApplicationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the application.
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: The name of the application.
          example: My Web Application
        description:
          type: string
          description: A brief description of the application.
          example: Customer portal application
        clientId:
          type: string
          description: The client ID for the application.
          example: myapp_client_id
        logoUrl:
          type: string
          format: uri
          description: The URL of the application's logo.
          example: https://myapp.example.com/logo.png
        authFlowId:
          type: string
          description: The ID of the authentication flow.
          example: edc013d0-e893-4dc0-990c-3e1d203e005b
        registrationFlowId:
          type: string
          description: The ID of the registration flow.
          example: 80024fb3-29ed-4c33-aa48-8aee5e96d522
        isRegistrationFlowEnabled:
          type: boolean
          description: Indicates if the registration flow is enabled for the application.
          example: true
        themeId:
          type: string
          format: uuid
          description: The ID of the theme configuration associated with this application.
        layoutId:
          type: string
          format: uuid
          description: The ID of the layout configuration associated with this application.
          example: 770e8400-e29b-41d4-a716-446655440002
        template:
          type: string
          description: The template type of the application.
          example: spa
    ApplicationListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 25
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 10
        applications:
          type: array
          items:
            $ref: "#/components/schemas/BasicApplicationResponse"
    AssertionConfig:
      type: object
      description: |
        Assertion configuration for application-level (root) assertions.
      properties:
        validityPeriod:
          type: integer
          description: The validity period of the token in seconds.
          example: 3600
        userAttributes:
          type: array
          items:
            type: string
          description: The user attributes to include in the token.
          example:
            - email
            - username
    AccessTokenConfig:
      type: object
      description: |
        Access token configuration for OAuth applications.
      properties:
        validityPeriod:
          type: integer
          description: The validity period of the access token in seconds. If not
            specified, falls back to application-level or deployment default.
          example: 3600
        userAttributes:
          type: array
          items:
            type: string
          description: The user attributes to include in the access token.
          example:
            - email
            - username
    IDTokenConfig:
      type: object
      description: |
        ID token configuration for OAuth applications.
      properties:
        validityPeriod:
          type: integer
          description: The validity period of the ID token in seconds. If not specified,
            falls back to application-level or deployment default.
          example: 3600
        userAttributes:
          type: array
          items:
            type: string
          description: The user attributes to include in the ID token. Only claims
            requested by scopes AND listed here will be included.
          example:
            - email
            - name
            - given_name
            - family_name
    UserInfoConfig:
      type: object
      description: UserInfo endpoint configuration for the OAuth application
      properties:
        userAttributes:
          type: array
          items:
            type: string
          description: |
            The user attributes to include in the userinfo response. 
            If not specified, falls back to ID token user attributes.
          example:
            - email
            - name
            - given_name
            - family_name
            - picture
    Certificate:
      type: object
      properties:
        type:
          type: string
          description: The type of the certificate.
          enum:
            - NONE
            - JWKS
            - JWKS_URI
          example: JWKS_URI
        value:
          type: string
          description: The value of the certificate.
          example: https://myapp.example.com/.well-known/jwks
    InboundAuthConfig:
      type: object
      properties:
        type:
          type: string
          description: The type of inbound authentication.
          enum:
            - oauth2
          example: oauth2
        config:
          $ref: "#/components/schemas/OAuthAppConfig"
    InboundAuthConfigComplete:
      type: object
      properties:
        type:
          type: string
          description: The type of inbound authentication.
          enum:
            - oauth2
          example: oauth2
        config:
          $ref: "#/components/schemas/OAuthAppConfigComplete"
    OAuthAppConfig:
      type: object
      properties:
        clientId:
          type: string
          description: The client ID for the OAuth application.
          example: myapp_client_id
        redirectUris:
          type: array
          items:
            type: string
            format: uri
          description: A list of redirect URIs for the OAuth application.
          example:
            - https://myapp.example.com/callback
            - https://myapp.example.com/oauth/callback
        grantTypes:
          type: array
          items:
            type: string
            enum:
              - authorization_code
              - client_credentials
              - refresh_token
              - implicit
              - password
              - urn:ietf:params:oauth:grant-type:token-exchange
          description: A list of grant types supported by the OAuth application. Defaults
            to ["authorization_code"] if not specified.
          example:
            - authorization_code
            - refresh_token
        responseTypes:
          type: array
          items:
            type: string
            enum:
              - code
              - token
          description: A list of response types supported by the OAuth application.
            Defaults to ["code"] if not specified.
          example:
            - code
        tokenEndpointAuthMethod:
          type: string
          enum:
            - client_secret_basic
            - client_secret_post
            - none
          description: The token endpoint authentication method for the OAuth application.
            Defaults to "client_secret_basic" if not specified.
          example: client_secret_basic
        pkceRequired:
          type: boolean
          description: Whether PKCE (Proof Key for Code Exchange) is required for this
            application.
          example: false
          default: false
        publicClient:
          type: boolean
          description: Whether the application is a public client (Mobile apps, SPAs,
            etc.), which cannot store secrets securely.
          example: false
          default: false
        scopes:
          type: array
          items:
            type: string
          description: List of scopes that the client can request.
          example:
            - openid
            - profile
            - email
        token:
          type: object
          properties:
            accessToken:
              $ref: "#/components/schemas/AccessTokenConfig"
            idToken:
              $ref: "#/components/schemas/IDTokenConfig"
        userInfo:
          $ref: "#/components/schemas/UserInfoConfig"
        scopeClaims:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Custom scope-to-claims mapping. Overrides default OIDC scope claims
            or defines custom scopes. Applies to both ID token and userinfo
            responses.
          example:
            profile:
              - name
              - family_name
              - given_name
              - picture
            employee:
              - emp_id
              - department
    OAuthAppConfigComplete:
      type: object
      properties:
        clientId:
          type: string
          description: The client ID for the OAuth application.
          example: myapp_client_id
        clientSecret:
          type: string
          description: The client secret for the OAuth application. Omitted for public
            clients.
          example: myapp_client_secret
        redirectUris:
          type: array
          items:
            type: string
            format: uri
          description: A list of redirect URIs for the OAuth application.
          example:
            - https://myapp.example.com/callback
            - https://myapp.example.com/oauth/callback
        grantTypes:
          type: array
          items:
            type: string
            enum:
              - authorization_code
              - client_credentials
              - refresh_token
              - implicit
              - password
              - urn:ietf:params:oauth:grant-type:token-exchange
          description: A list of grant types supported by the OAuth application. Defaults
            to ["authorization_code"] if not specified.
          example:
            - authorization_code
            - refresh_token
        responseTypes:
          type: array
          items:
            type: string
            enum:
              - code
              - token
          description: A list of response types supported by the OAuth application.
            Defaults to ["code"] if not specified.
          example:
            - code
        tokenEndpointAuthMethod:
          type: string
          enum:
            - client_secret_basic
            - client_secret_post
            - none
          description: The token endpoint authentication method for the OAuth application.
            Defaults to "client_secret_basic" if not specified.
          example: client_secret_basic
        pkceRequired:
          type: boolean
          description: Whether PKCE (Proof Key for Code Exchange) is required for this
            application.
          example: false
          default: false
        publicClient:
          type: boolean
          description: Whether the application is a public client (Mobile apps, SPAs,
            etc.), which cannot store secrets securely.
          example: false
          default: false
        scopes:
          type: array
          items:
            type: string
          description: List of scopes that the client can request.
          example:
            - openid
            - profile
            - email
        token:
          type: object
          properties:
            accessToken:
              $ref: "#/components/schemas/AccessTokenConfig"
            idToken:
              $ref: "#/components/schemas/IDTokenConfig"
        userInfo:
          $ref: "#/components/schemas/UserInfoConfig"
        scopeClaims:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Custom scope-to-claims mapping. Overrides default OIDC scope claims
            or defines custom scopes. Applies to both ID token and userinfo
            responses.
          example:
            profile:
              - name
              - family_name
              - given_name
              - picture
            employee:
              - emp_id
              - department
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        description:
          type: string
    CredentialAuthRequest:
      type: object
      properties:
        identifiers:
          type: object
          description: Map of user identifiers (e.g., username, email, phone number)
          additionalProperties: true
          example:
            email: jane.doe@example.com
        credentials:
          type: object
          description: Map of user credentials (e.g., password, pin)
          additionalProperties: true
          example:
            password: SecurePassword123!
        skipAssertion:
          type: boolean
          description: Skip generating assertion token in the response
          default: false
          example: false
        assertion:
          type: string
          description: Optional existing JWT assertion token to enrich with new
            authentication
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      required:
        - identifiers
        - credentials
      additionalProperties: false
    SendOtpAuthRequest:
      type: object
      properties:
        senderId:
          type: string
          description: ID of the message notification sender to use
          example: 550e8400-e29b-41d4-a716-446655440000
        recipient:
          type: string
          description: Recipient's mobile number
          example: "+1234567890"
      required:
        - senderId
        - recipient
    SendOtpAuthResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the OTP send request
          example: SUCCESS
        sessionToken:
          type: string
          description: JWT token for the authentication session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    VerifyOtpAuthRequest:
      type: object
      properties:
        sessionToken:
          type: string
          description: JWT token for the OTP session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        otp:
          type: string
          description: The OTP code received by the user
          example: "123456"
        skipAssertion:
          type: boolean
          description: Skip generating assertion token in the response
          default: false
          example: false
        assertion:
          type: string
          description: Optional existing JWT assertion token to enrich with new
            authentication
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      required:
        - sessionToken
        - otp
    AuthenticationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the authenticated user
        type:
          type: string
          description: The type of the authenticated user
        organization_unit:
          type: string
          format: uuid
          description: The organization unit ID of the authenticated user
        assertion:
          type: string
          description: JWT assertion token for the authenticated user
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    IDPAuthInitRequest:
      type: object
      required:
        - idpId
      properties:
        idpId:
          type: string
          description: Identity provider ID
          example: 550e8400-e29b-41d4-a716-446655440000
    IDPAuthInitResponse:
      type: object
      properties:
        redirectUrl:
          type: string
          description: URL to redirect the user for authentication
          example: https://accounts.google.com/o/oauth2/auth?client_id=your-client-id&response_type=code&scope=openid%20email%20profile&redirect_uri=https://yourapp.com/callback
        sessionToken:
          type: string
          description: JWT token for the authentication session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    IDPAuthFinishRequest:
      type: object
      required:
        - sessionToken
        - code
      properties:
        sessionToken:
          type: string
          description: JWT token for the authentication session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        code:
          type: string
          description: Authorization code received from the identity provider
        skipAssertion:
          type: boolean
          description: Skip generating assertion token in the response
          default: false
          example: false
        assertion:
          type: string
          description: Optional existing JWT assertion token to enrich with new
            authentication
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    WebAuthnStartRequest:
      type: object
      properties:
        user_id:
          type: string
          description: User ID of the user to authenticate
          example: 550e8400-e29b-41d4-a716-446655440000
        relying_party_id:
          type: string
          description: Relying Party ID (typically the domain)
          example: example.com
      required:
        - user_id
        - relying_party_id
    WebAuthnStartResponse:
      type: object
      properties:
        publicKeyCredentialRequestOptions:
          type: object
          description: PublicKeyCredentialRequestOptions as per WebAuthn standard
          properties:
            challenge:
              type: string
              description: Base64url-encoded challenge for the authentication ceremony
              example: Z29yZG9uQGV4YW1wbGUuY29tMjAyMS0wMy0xMlQxMjo0NTowMFo
            timeout:
              type: integer
              description: Time in milliseconds that the user has to respond to the prompt
              example: 60000
            rpId:
              type: string
              description: Relying Party identifier
              example: example.com
            allowCredentials:
              type: array
              description: List of credentials the server would like the user to authenticate
                with
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of the credential
                    example: public-key
                  id:
                    type: string
                    description: Base64url-encoded credential ID
                    example: AdC-ff_z-Z1gY2s6e_2A-g
                  transports:
                    type: array
                    description: Hints about where the credential might be stored
                    items:
                      type: string
                      enum:
                        - usb
                        - nfc
                        - ble
                        - internal
                        - hybrid
                    example:
                      - internal
                      - hybrid
            userVerification:
              type: string
              description: User verification requirement
              enum:
                - required
                - preferred
                - discouraged
              example: preferred
          required:
            - challenge
          example:
            challenge: Z29yZG9uQGV4YW1wbGUuY29tMjAyMS0wMy0xMlQxMjo0NTowMFo
            timeout: 60000
            rpId: example.com
            allowCredentials:
              - type: public-key
                id: AdC-ff_z-Z1gY2s6e_2A-g
                transports:
                  - internal
                  - hybrid
            userVerification: preferred
        sessionToken:
          type: string
          description: JWT token for the WebAuthn authentication session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      required:
        - publicKeyCredentialRequestOptions
        - sessionToken
    WebAuthnFinishRequest:
      type: object
      properties:
        publicKeyCredential:
          type: object
          description: PublicKeyCredential as per WebAuthn standard
          properties:
            id:
              type: string
              description: Base64url-encoded credential ID
              example: AdC-ff_z-Z1gY2s6e_2A-g
            rawId:
              type: string
              description: Base64url-encoded raw credential ID
              example: AdC-ff_z-Z1gY2s6e_2A-g
            type:
              type: string
              description: Type of the credential
              example: public-key
            response:
              type: object
              description: AuthenticatorAssertionResponse
              properties:
                clientDataJSON:
                  type: string
                  description: Base64url-encoded client data JSON
                  example: eyJjaGFsbGVuZ2UiOiJaMm95Wm05eVpHOXVRR1Y0WVcxd2JHVXVZMjl0TWpBeU1TMHdNeTB4TWxReE1qbzBOVG93TUZvIiwidHlwZSI6IndlYmF1dGhuLmdldCIsIm9yaWdpbiI6Imh0dHBzOi8vZXhhbXBsZS5jb20ifQ
                authenticatorData:
                  type: string
                  description: Base64url-encoded authenticator data
                  example: SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAAAQ
                signature:
                  type: string
                  description: Base64url-encoded signature
                  example: MEUCIQCHLpP8Z8AsiWEnMLHLmVzzuoMdl2MFAAAAAQCHLpP8Z8AsiWEnMLHLmVzzuoMdl2MFAAAAAQ
                userHandle:
                  type: string
                  description: Base64url-encoded user handle (optional)
                  example: aWQxMjM0NQ
              required:
                - clientDataJSON
                - authenticatorData
                - signature
            authenticatorAttachment:
              type: string
              description: Authenticator attachment modality
              enum:
                - platform
                - cross-platform
              example: platform
          required:
            - id
            - rawId
            - type
            - response
          example:
            id: AdC-ff_z-Z1gY2s6e_2A-g
            rawId: AdC-ff_z-Z1gY2s6e_2A-g
            type: public-key
            response:
              clientDataJSON: eyJjaGFsbGVuZ2UiOiJaMm95Wm05eVpHOXVRR1Y0WVcxd2JHVXVZMjl0TWpBeU1TMHdNeTB4TWxReE1qbzBOVG93TUZvIiwidHlwZSI6IndlYmF1dGhuLmdldCIsIm9yaWdpbiI6Imh0dHBzOi8vZXhhbXBsZS5jb20ifQ
              authenticatorData: SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAAAQ
              signature: MEUCIQCHLpP8Z8AsiWEnMLHLmVzzuoMdl2MFAAAAAQ
              userHandle: aWQxMjM0NQ
            authenticatorAttachment: platform
        sessionToken:
          type: string
          description: JWT token for the WebAuthn authentication session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        skipAssertion:
          type: boolean
          description: Skip generating assertion token in the response
          default: false
          example: false
        assertion:
          type: string
          description: Optional existing JWT assertion token to enrich with new
            authentication
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      required:
        - publicKeyCredential
        - sessionToken
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
        description:
          type: string
          description: Detailed error description
    ClientErrorResponse:
      allOf:
        - $ref: "#/components/schemas/ErrorResponse"
        - type: object
    ServerErrorResponse:
      allOf:
        - $ref: "#/components/schemas/ErrorResponse"
        - type: object
      example:
        code: SSE-5000
        message: Internal server error
        description: An unexpected error occurred while processing the request
    ThemeRequest:
      type: object
      required:
        - handle
        - displayName
        - theme
      properties:
        handle:
          type: string
          description: Unique kebab-case identifier for the theme
          example: corporate-theme
        displayName:
          type: string
          description: Display name for the theme
          example: Corporate Theme
        description:
          type: string
          description: Description of the theme
          example: Dracula theme...
        theme:
          type: object
          description: Theme configuration as a JSON object
          additionalProperties: true
          example:
            primaryColor: "#1976d2"
            secondaryColor: "#dc004e"
            fontFamily: Roboto
            borderRadius: 4px
    ThemeResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the theme
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        handle:
          type: string
          description: Unique kebab-case identifier for the theme
          example: corporate-theme
        displayName:
          type: string
          description: Display name for the theme
          example: Corporate Theme
        description:
          type: string
          description: Description of the theme
          example: Dracula theme...
        theme:
          type: object
          description: Theme configuration as a JSON object
          additionalProperties: true
          example:
            primaryColor: "#1976d2"
            secondaryColor: "#dc004e"
            fontFamily: Roboto
            borderRadius: 4px
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the theme was created (ISO 8601 format)
          example: 2024-01-15T10:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the theme was last updated (ISO 8601 format)
          example: 2024-01-20T14:45:00Z
    ThemeListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the theme
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        handle:
          type: string
          description: Unique kebab-case identifier for the theme
          example: corporate-theme
        displayName:
          type: string
          description: Display name for the theme
          example: Corporate Theme
        description:
          type: string
          description: Description of the theme
          example: A timeless theme with warm accents.
        defaultColorScheme:
          type: string
          description: The name of the default color scheme for this theme (e.g. "light"
            or "dark")
          example: light
        primaryColor:
          type: string
          description: The primary color hex value from the default color scheme's palette
          example: "#ff7300"
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the theme was created (ISO 8601 format)
          example: 2024-01-15T10:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the theme was last updated (ISO 8601 format)
          example: 2024-01-20T14:45:00Z
    ThemeListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Total number of themes
          example: 10
        startIndex:
          type: integer
          description: Index of the first result
          example: 1
        count:
          type: integer
          description: Number of results in this response
          example: 10
        links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  example: /design/themes?limit=10&offset=0
            next:
              type: object
              properties:
                href:
                  type: string
                  example: /design/themes?limit=10&offset=10
            previous:
              type: object
              properties:
                href:
                  type: string
                  example: /design/themes?limit=10&offset=0
        themes:
          type: array
          items:
            $ref: "#/components/schemas/ThemeListItem"
    LayoutRequest:
      type: object
      required:
        - handle
        - displayName
        - layout
      properties:
        handle:
          type: string
          description: Unique kebab-case identifier for the layout
          example: modern-layout
        displayName:
          type: string
          description: Display name for the layout
          example: Modern Layout
        layout:
          type: object
          description: Layout configuration as a JSON object
          additionalProperties: true
          example:
            contentAlignment: center
            maxWidth: 1200px
            showLogo: true
            logoPosition: top
    LayoutResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the layout
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        handle:
          type: string
          description: Unique kebab-case identifier for the layout
          example: modern-layout
        displayName:
          type: string
          description: Display name for the layout
          example: Modern Layout
        layout:
          type: object
          description: Layout configuration as a JSON object
          additionalProperties: true
          example:
            contentAlignment: center
            maxWidth: 1200px
            showLogo: true
            logoPosition: top
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the layout was created (ISO 8601 format)
          example: 2024-01-15T10:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the layout was last updated (ISO 8601 format)
          example: 2024-01-20T14:45:00Z
        isReadOnly:
          type: boolean
          description: Indicates whether the layout is read-only (declarative)
          example: false
    LayoutListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the layout
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        handle:
          type: string
          description: Unique kebab-case identifier for the layout
          example: modern-layout
        displayName:
          type: string
          description: Display name for the layout
          example: Modern Layout
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the layout was created (ISO 8601 format)
          example: 2024-01-15T10:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the layout was last updated (ISO 8601 format)
          example: 2024-01-20T14:45:00Z
        isReadOnly:
          type: boolean
          description: Indicates whether the layout is read-only (declarative)
          example: false
    LayoutListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Total number of layouts
          example: 5
        startIndex:
          type: integer
          description: Index of the first result
          example: 1
        count:
          type: integer
          description: Number of results in this response
          example: 5
        links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  example: /design/layouts?limit=10&offset=0
            next:
              type: object
              properties:
                href:
                  type: string
                  example: /design/layouts?limit=10&offset=10
            previous:
              type: object
              properties:
                href:
                  type: string
                  example: /design/layouts?limit=10&offset=0
        layouts:
          type: array
          items:
            $ref: "#/components/schemas/LayoutListItem"
    DesignResolveResponse:
      type: object
      properties:
        id:
          type: string
          description: Combined identifier (theme-id|layout-id) or single ID if only one
            is configured
          example: theme-id|layout-id
        displayName:
          type: string
          description: Combined display name or single display name
          example: Corporate Theme / Modern Layout
        design:
          type: object
          description: Merged design configuration from theme and layout (layout takes
            precedence)
          additionalProperties: true
          example:
            primaryColor: "#1976d2"
            secondaryColor: "#dc004e"
            fontFamily: Inter
            borderRadius: 8px
            contentAlignment: center
            maxWidth: 1200px
            showLogo: true
            logoPosition: top
    InitialFlowRequest:
      type: object
      required:
        - applicationId
        - flowType
      properties:
        applicationId:
          type: string
          description: Identifier of the application initiating the flow
          example: 550e8400-e29b-41d4-a716-446655440000
        flowType:
          type: string
          description: Type of the flow to execute
          enum:
            - AUTHENTICATION
            - REGISTRATION
          example: AUTHENTICATION
    SubSequentFlowRequest:
      type: object
      required:
        - executionId
      properties:
        executionId:
          type: string
          description: Identifier of an existing flow execution
          example: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
        actionId:
          type: string
          description: Identifier of the action to execute in the flow
          example: basic_auth
        inputs:
          type: object
          description: Input data provided for the flow step execution
          example:
            username: thor
            password: thor@123
    IncompleteFlowResponse:
      type: object
      required:
        - executionId
        - flowStatus
        - stepId
        - type
      properties:
        executionId:
          type: string
          description: Unique identifier of the flow execution
          example: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
        flowStatus:
          type: string
          description: Status of the flow execution
          example: PROMPT_ONLY
        stepId:
          type: string
          description: Identifier of the current flow step
          example: 3071b6c6-0119-465c-b00b-3a0e6f88a730
        type:
          type: string
          description: Type of flow step response
          example: VIEW
        data:
          allOf:
            - $ref: "#/components/schemas/Data"
          description: Data for the next step in the flow
    CompleteFlowResponse:
      type: object
      required:
        - executionId
        - flowStatus
        - assertion
      properties:
        executionId:
          type: string
          description: Unique identifier of the flow execution
          example: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
        flowStatus:
          type: string
          description: Status of the flow execution
          example: PROMPT_ONLY
        assertion:
          type: string
          description: Authentication assertion. This will be the JWT authentication token
          example: <jwt_token>
    ErrorFlowResponse:
      type: object
      required:
        - executionId
        - flowStatus
        - failureReason
      properties:
        executionId:
          type: string
          description: Unique identifier of the flow execution
          example: 2c6d4c45-3de9-4a70-ae6b-ba1d034af6bc
        flowStatus:
          type: string
          description: Status of the flow execution
          example: ERROR
        failureReason:
          type: string
          description: Reason for the failure in the flow execution
          example: Invalid credentials
    Data:
      type: object
      properties:
        inputs:
          type: array
          items:
            $ref: "#/components/schemas/Input"
          description: Required input data for the next flow step
        redirectURL:
          type: string
          description: Redirect URL for the next step in the flow if applicable
          example: https://example.com/redirect
        additionalData:
          type: object
          additionalProperties:
            type: string
          description: Additional information provided by the flow step
          example:
            idpName: <idp_name>
        actions:
          type: array
          items:
            $ref: "#/components/schemas/Action"
          description: Available actions for the current flow step
        meta:
          type: object
          description: >
            UI rendering metadata for display-only PROMPT nodes, returned when
            executing in verbose mode. 

            Contains a `components` array describing the elements to render
            (headings, body text, images, etc.).
          example:
            components:
              - id: heading_001
                type: TEXT
                category: DISPLAY
                variant: HEADING_3
                label: You're All Set
              - id: body_001
                type: TEXT
                category: DISPLAY
                variant: BODY_1
                label: You have successfully completed the registration.
    Action:
      type: object
      required:
        - id
        - name
        - handle
        - permission
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the action
        name:
          type: string
          description: Display name of the action
        handle:
          type: string
          description: Immutable and unique under resource server or resource. Identifier
            used for permission derivation
        description:
          type: string
          nullable: true
          description: Optional description of the action
        permission:
          type: string
          description: Derived permission string based on handle hierarchy
    Input:
      type: object
      properties:
        ref:
          type: string
          description: Reference name of the input field, used for mapping user inputs to
            the meta components
          example: input_username
        identifier:
          type: string
          description: Name of the input field
          example: username
        type:
          type: string
          description: Type of the input field
          example: TEXT_INPUT
        required:
          type: boolean
          description: Whether the input is required
          example: true
    FlowListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 5
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 3
        flows:
          type: array
          items:
            $ref: "#/components/schemas/BasicFlowDefinitionResponse"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
          description: Navigation links for pagination.
      example:
        totalResults: 5
        startIndex: 1
        count: 3
        flows:
          - id: 641af221-75ff-4247-ab1f-ff139040a91b
            flowType: AUTHENTICATION
            name: Basic Authentication Flow
            handle: default-basic-flow
            activeVersion: 2
            createdAt: 2024-01-15T10:20:30Z
            updatedAt: 2024-02-20T14:25:35Z
          - id: 2sd4f6g7-h8i9-0j1k-2l3m-4n5o6p7q8r9s
            flowType: REGISTRATION
            name: Basic Registration Flow
            handle: basic-registration-flow
            activeVersion: 7
            createdAt: 2024-03-10T09:15:25Z
            updatedAt: 2024-04-12T11:30:40Z
          - id: b12c3d45-6789-4e0f-9abc-def123456789
            flowType: REGISTRATION
            name: Google Registration Flow
            handle: google-registration-flow
            activeVersion: 1
            createdAt: 2024-05-05T08:10:20Z
            updatedAt: 2024-06-01T12:00:00Z
        links:
          - href: /flows?offset=3&limit=3
            rel: next
    FlowVersionListResponse:
      type: object
      properties:
        totalVersions:
          type: integer
          description: Total number of versions available for this flow
          example: 8
        versions:
          type: array
          items:
            $ref: "#/components/schemas/FlowVersionInfo"
          description: List of flow versions (most recent first)
      example:
        totalVersions: 8
        versions:
          - version: 8
            createdAt: 2024-12-01T15:30:00Z
            isActive: true
          - version: 7
            createdAt: 2024-11-25T10:15:00Z
            isActive: false
          - version: 6
            createdAt: 2024-11-20T14:20:00Z
            isActive: false
    FlowVersionInfo:
      type: object
      required:
        - version
        - createdAt
        - isActive
      properties:
        version:
          type: integer
          description: Version number
          example: 5
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this specific version was created
        isActive:
          type: boolean
          description: Indicates if this is the currently active version
          example: false
    RestoreVersionRequest:
      type: object
      required:
        - version
      properties:
        version:
          type: integer
          description: Version number to restore to
          minimum: 1
          example: 5
      example:
        version: 5
    Link:
      type: object
      properties:
        href:
          type: string
          example: organization-units?offset=20&limit=10
        rel:
          type: string
          example: next
    BasicFlowDefinitionResponse:
      type: object
      required:
        - id
        - flowType
        - name
        - handle
        - activeVersion
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Unique identifier for the flow
        flowType:
          type: string
          enum:
            - AUTHENTICATION
            - REGISTRATION
        name:
          type: string
          description: Name of the flow
          example: Basic Authentication Flow
        handle:
          type: string
          description: >
            URL-friendly handle for the flow (lowercase letters, numbers,
            hyphens, and underscores only)

            Once set, the handle cannot be changed.
          pattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$
          example: default-basic-flow
        activeVersion:
          type: integer
          description: The version number that is currently active
          example: 5
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the flow was initially created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the flow was last modified
    FlowDefinitionRequest:
      type: object
      required:
        - name
        - flowType
        - handle
        - nodes
      properties:
        name:
          type: string
          description: Name of the flow
          example: Basic Authentication Flow
        handle:
          type: string
          description: >
            URL-friendly handle for the flow (lowercase letters, numbers,
            hyphens, and underscores only)

            Once set, the handle cannot be changed.
          pattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$
          example: default-basic-flow
        flowType:
          type: string
          enum:
            - AUTHENTICATION
            - REGISTRATION
          description: |
            Type of flow
          example: AUTHENTICATION
        nodes:
          type: array
          minItems: 2
          items:
            $ref: "#/components/schemas/Node"
          description: List of nodes that define the flow graph
      example:
        name: Basic Authentication Flow
        handle: default-basic-flow
        flowType: AUTHENTICATION
        nodes: &a1
          - id: node_000
            type: START
            layout:
              size:
                width: 180
                height: 80
              position:
                x: 50
                y: 50
            onSuccess: node_001
          - id: node_001
            type: PROMPT
            layout:
              size:
                width: 320
                height: 450
              position:
                x: 50
                y: 180
            meta:
              components:
                - type: TEXT
                  id: text_001
                  label: "{{ t(signin:heading.label) }}"
                  variant: HEADING_01
                - type: BLOCK
                  id: block_001
                  components:
                    - type: TEXT_INPUT
                      id: input_001
                      label: "{{ t(signin:fields.username.label) }}"
                      required: true
                      placeholder: "{{ t(signin:fields.username.placeholder) }}"
                    - type: PASSWORD_INPUT
                      id: input_002
                      label: "{{ t(signin:fields.password.label) }}"
                      required: true
                      placeholder: "{{ t(signin:fields.password.placeholder) }}"
                    - type: ACTION
                      id: action_001
                      label: "{{ t(signin:buttons.submit) }}"
                - type: DIVIDER
                  id: divider_001
                  label: "{{ t(signin:divider.or.label) }}"
                - type: ACTION
                  id: action_002
                  label: "{{ t(signin:buttons.continue.with.sms.otp.label) }}"
            inputs:
              - ref: input_001
                type: TEXT_INPUT
                identifier: username
                required: true
              - ref: input_002
                type: PASSWORD_INPUT
                identifier: password
                required: true
            actions:
              - ref: action_001
                nextNode: node_004
              - ref: action_002
                nextNode: node_002
          - id: node_002
            type: TASK_EXECUTION
            layout:
              size:
                width: 200
                height: 120
              position:
                x: 450
                y: 300
            executor:
              name: SendSMSExecutor
            properties:
              senderId: <SENDER_ID>
            onSuccess: node_003
            onFailure: node_007
          - id: node_003
            type: PROMPT
            layout:
              size:
                width: 320
                height: 380
              position:
                x: 700
                y: 280
            meta:
              components:
                - type: HEADING
                  id: heading_003
                  label: "{{ t(sms.otp:verify.heading) }}"
                - type: TEXT
                  id: text_003
                  label: "{{ t(sms.otp:verify.heading.label) }}"
                  variant: HEADING_01
                - type: OTP_INPUT
                  id: otp_001
                  label: "{{ t(sms.otp:verify.otp.input.label) }}"
                  length: 6
                  required: true
                - type: ACTION
                  id: action_003
                  label: "{{ t(sms.otp:verify.buttons.submit) }}"
                - type: ACTION
                  id: action_004
                  label: "{{ t(sms.otp:verify.buttons.resend) }}"
            inputs:
              - ref: otp_001
                type: OTP_INPUT
                identifier: otp
                required: true
            actions:
              - ref: action_003
                nextNode: node_005
              - ref: action_004
                nextNode: node_002
          - id: node_004
            type: TASK_EXECUTION
            layout:
              size:
                width: 200
                height: 140
              position:
                x: 450
                y: 100
            executor:
              name: BasicAuthExecutor
            inputs:
              - ref: input_001
                identifier: username
                type: TEXT_INPUT
                required: true
              - ref: input_002
                identifier: password
                type: PASSWORD_INPUT
                required: true
            onSuccess: node_008
          - id: node_005
            type: TASK_EXECUTION
            layout:
              size:
                width: 200
                height: 140
              position:
                x: 1100
                y: 320
            executor:
              name: VerifyOTPExecutor
            properties:
              senderId: <SENDER_ID>
            inputs:
              - ref: otp_001
                identifier: otp
                type: OTP_INPUT
                required: true
            onSuccess: node_008
          - id: node_007
            type: PROMPT
            layout:
              size:
                width: 300
                height: 280
              position:
                x: 450
                y: 480
            meta:
              components:
                - type: HEADING
                  id: heading_007
                  label: "{{ t(sms.otp:error.heading) }}"
                - type: TEXT
                  id: text_007
                  label: "{{ t(sms.otp:error.message) }}"
                - type: ACTION
                  id: action_007
                  label: "{{ t(sms.otp:error.buttons.retry) }}"
            actions:
              - ref: action_007
                nextNode: node_002
          - id: node_008
            type: END
            layout:
              size:
                width: 180
                height: 80
              position:
                x: 1400
                y: 200
    FlowDefinitionResponse:
      type: object
      required:
        - id
        - name
        - flowType
        - handle
        - activeVersion
        - nodes
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Unique identifier for the flow
          example: a23b45c6-d7e8-90f1-2345-6789abcdef01
        name:
          type: string
          description: Name of the flow
          example: Basic Authentication Flow
        flowType:
          type: string
          enum:
            - AUTHENTICATION
            - REGISTRATION
          description: |
            Type of flow
          example: AUTHENTICATION
        handle:
          type: string
          description: >
            URL-friendly handle for the flow (lowercase letters, numbers,
            hyphens, and underscores only)

            Once set, the handle cannot be changed.
          pattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$
          example: default-basic-flow
        activeVersion:
          type: integer
          description: The version number that is currently active
          example: 5
        nodes:
          type: array
          minItems: 2
          items:
            $ref: "#/components/schemas/Node"
          description: List of nodes that define the flow graph
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the flow was initially created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the flow was last modified
      example:
        id: a23b45c6-d7e8-90f1-2345-6789abcdef01
        name: Basic Authentication Flow
        flowType: AUTHENTICATION
        handle: default-basic-flow
        activeVersion: 5
        nodes: *a1
        createdAt: 2024-06-15T10:20:30Z
        updatedAt: 2024-06-20T14:25:35Z
    FlowVersionResponse:
      type: object
      required:
        - id
        - name
        - flowType
        - handle
        - version
        - isActive
        - nodes
        - createdAt
      properties:
        id:
          type: string
          description: Unique identifier for the flow
          example: a23b45c6-d7e8-90f1-2345-6789abcdef01
        name:
          type: string
          description: Name of the flow
          example: Basic Authentication Flow
        flowType:
          type: string
          enum:
            - AUTHENTICATION
            - REGISTRATION
          description: |
            Type of flow
          example: AUTHENTICATION
        handle:
          type: string
          description: >
            URL-friendly handle for the flow (lowercase letters, numbers,
            hyphens, and underscores only)

            Once set, the handle cannot be changed.
          pattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$
          example: default-basic-flow
        version:
          type: integer
          description: Version number of this flow snapshot
          example: 3
        isActive:
          type: boolean
          description: Indicates if this is the currently active version of the flow
          example: false
        nodes:
          type: array
          minItems: 2
          items:
            $ref: "#/components/schemas/Node"
          description: List of nodes that define the flow graph
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this specific version was created
      example:
        id: a23b45c6-d7e8-90f1-2345-6789abcdef01
        name: Basic Authentication Flow
        flowType: AUTHENTICATION
        handle: default-basic-flow
        version: 3
        isActive: false
        nodes: *a1
        createdAt: 2024-06-15T10:20:30Z
    Node:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: Unique identifier for the node within the flow
          example: node_001
        type:
          type: string
          enum:
            - START
            - PROMPT
            - TASK_EXECUTION
            - END
          description: |
            Type of node
          example: PROMPT
        layout:
          allOf:
            - $ref: "#/components/schemas/NodeLayout"
        meta:
          description: Optional UI metadata for PROMPT nodes (verbose mode)
          allOf:
            - $ref: "#/components/schemas/NodeMeta"
        inputs:
          type: array
          items:
            $ref: "#/components/schemas/NodeInput"
          description: >
            Input definitions for PROMPT nodes (required) and TASK_EXECUTION
            nodes (optional).

            For TASK_EXECUTION nodes, inputs indicate which identifiers the
            executor should use.
        actions:
          type: array
          items:
            $ref: "#/components/schemas/NodeAction"
          description: Available actions for PROMPT nodes
        properties:
          type: object
          additionalProperties: true
          description: >
            Node-level properties for configuration (e.g., senderId for
            notification executors,

            idpId for social login executors)
          example:
            senderId: <SENDER_ID>
        executor:
          description: Executor configuration for TASK_EXECUTION nodes (required)
          allOf:
            - $ref: "#/components/schemas/Executor"
        onSuccess:
          type: string
          description: Next node ID on successful execution (START and TASK_EXECUTION nodes)
          example: node_003
        onFailure:
          type: string
          description: Next node ID on failed execution (TASK_EXECUTION nodes)
          example: node_007
        onIncomplete:
          type: string
          description: >
            For TASK_EXECUTION nodes: ID of the PROMPT node to transition to
            when user input

            is required to complete the task.
          example: node_003
        next:
          type: string
          description: >
            For display-only PROMPT nodes: ID of the next node to automatically
            transition to

            after the display content is rendered. Mutually exclusive with
            `prompts`.
          example: node_005
        message:
          type: string
          description: >
            For display-only PROMPT nodes: a plain-text message returned in
            non-verbose mode

            alongside the flow status, intended for lightweight clients that do
            not process

            the full meta/components payload.
          example: Registration complete. You may now sign in.
    NodeLayout:
      type: object
      description: >
        Layout information for the flow composer UI. This metadata is used 

        only by the visual flow composer to position and size nodes on the
        canvas. 
      properties:
        size:
          type: object
          description: Dimensions of the node in the flow composer canvas
          required:
            - width
            - height
          properties:
            width:
              type: number
              description: Width of the node in pixels
              example: 200
            height:
              type: number
              description: Height of the node in pixels
              example: 150
        position:
          type: object
          description: Position of the node in the flow composer canvas
          required:
            - x
            - y
          properties:
            x:
              type: number
              description: X-coordinate of the node
              example: 100
            y:
              type: number
              description: Y-coordinate of the node
              example: 100
      example:
        size:
          width: 200
          height: 150
        position:
          x: 100
          y: 100
    NodeMeta:
      type: object
      description: UI metadata for rendering PROMPT nodes in verbose mode
      properties:
        components:
          type: array
          items:
            $ref: "#/components/schemas/Component"
          description: UI components to render (headings, inputs, buttons, etc.)
    NodeInput:
      type: object
      required:
        - type
        - identifier
        - required
      properties:
        ref:
          type: string
          description: >
            Reference to the input component ID. For PROMPT nodes, this refers
            to components

            in meta.components. Optional but recommended for better

            flow visualization and debugging.
          example: input_001
        type:
          type: string
          description: Input type (TEXT_INPUT, PASSWORD_INPUT, OTP_INPUT, etc.)
          example: TEXT_INPUT
        identifier:
          type: string
          description: The mapped attribute identifier (e.g., username, password, otp)
          example: username
        required:
          type: boolean
          description: Whether this input is required
          example: true
    NodeAction:
      type: object
      required:
        - ref
        - nextNode
      properties:
        ref:
          type: string
          description: Reference to the action component ID in meta.components
          example: action_001
        type:
          type: string
          description: >
            Optional action type forwarded to the next executor so it can
            determine which

            processing path to take. Predefined values are `SUBMIT`
            (approve/confirm) and

            `REJECT` (deny/cancel). If omitted, no action-type hint is
            forwarded.
          example: SUBMIT
        nextNode:
          type: string
          description: ID of the next node to navigate to when this action is triggered
          example: node_004
    Executor:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: |
            Name of the registered executor
          example: BasicAuthExecutor
    Component:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: Unique identifier for the component
          example: input_001
        type:
          type: string
          description: |
            Component type. Common types:
            - TEXT, HEADING: Display text elements
            - TEXT_INPUT, PASSWORD_INPUT, OTP_INPUT: Input fields
            - ACTION: Buttons and clickable elements
            - BLOCK: Container for grouping components
            - DIVIDER: Visual separator
          example: TEXT_INPUT
        label:
          type: string
          description: Display label or text content (use {{ t(namespace:key) }} for i18n
            or plain text)
          example: "{{ t(signin:fields.username.label) }}"
        variant:
          type: string
          description: Component style variant (e.g., HEADING_01, PRIMARY, etc.)
          example: HEADING_01
        required:
          type: boolean
          description: Whether the component is required (for input fields)
          example: true
        placeholder:
          type: string
          description: Placeholder text for input fields (use {{ t(namespace:key) }} for
            i18n or plain text)
          example: "{{ t(signin:fields.username.placeholder) }}"
        length:
          type: integer
          description: Length specification (e.g., for OTP_INPUT)
          example: 6
        components:
          type: array
          items:
            $ref: "#/components/schemas/Component"
          description: Nested child components (for BLOCK type)
    ClientError:
      type: object
      properties:
        code:
          type: string
          description: The error code
          example: FMS-1001
        message:
          type: string
          description: The error message
          example: Invalid request format
        description:
          type: string
          description: A detailed description of the error
          example: The request body is malformed or contains invalid data
    ServerError:
      type: object
      properties:
        code:
          type: string
          description: The server error code
          example: SSE-5000
        message:
          type: string
          description: The server error message
          example: Internal server error
        description:
          type: string
          description: A detailed description of the server error
          example: An unexpected error occurred while processing the request
    FlowMetadataResponse:
      type: object
      required:
        - isRegistrationFlowEnabled
        - design
        - i18n
      properties:
        isRegistrationFlowEnabled:
          type: boolean
          description: Indicates if registration flow is enabled for the entity
          example: true
        application:
          $ref: "#/components/schemas/ApplicationMetadata"
        ou:
          $ref: "#/components/schemas/OUMetadata"
        design:
          $ref: "#/components/schemas/DesignMetadata"
        i18n:
          $ref: "#/components/schemas/I18nMetadata"
    ApplicationMetadata:
      type: object
      description: Application metadata (only present when type=APP)
      properties:
        id:
          type: string
          format: uuid
          description: Application ID
          example: 60a9b38b-6eba-9f9e-55f9-267067de4680
        name:
          type: string
          description: Application name
          example: My Web Application
        description:
          type: string
          description: Application description
          example: My web application for managing resources
        logoUrl:
          type: string
          format: uri
          description: Application logo URL
          example: https://myapp.example.com/logo.png
        url:
          type: string
          format: uri
          description: Application URL
          example: https://myapp.example.com
        tosUri:
          type: string
          format: uri
          description: Terms of Service URI
          example: https://myapp.example.com/terms
        policyUri:
          type: string
          format: uri
          description: Privacy Policy URI
          example: https://myapp.example.com/privacy
    OUMetadata:
      type: object
      description: |
        Organization unit metadata.
        - Always present when `type=OU`
        - For `type=APP`, only included when deployment has exactly one OU
      properties:
        id:
          type: string
          format: uuid
          description: Organization unit ID
          example: fe447a2f-29c5-4e33-ac8f-d77be15fdb32
        handle:
          type: string
          description: Organization unit handle
          example: default
        name:
          type: string
          description: Organization unit name
          example: Default Organization Unit
        description:
          type: string
          description: Organization unit description
          example: Default organization unit for the deployment
        logoUrl:
          type: string
          format: uri
          description: Organization unit logo URL
          example: https://myapp.example.com/logo.png
        tosUri:
          type: string
          format: uri
          description: Terms of Service URI
          example: https://myapp.example.com/terms
        policyUri:
          type: string
          format: uri
          description: Privacy Policy URI
          example: https://myapp.example.com/privacy
        cookiePolicyUri:
          type: string
          format: uri
          description: Cookie Policy URI
          example: https://myapp.example.com/cookies
    DesignMetadata:
      type: object
      required:
        - theme
        - layout
      properties:
        theme:
          type: object
          description: Resolved theme configuration
          additionalProperties: true
        layout:
          type: object
          description: Resolved layout configuration
          additionalProperties: true
    I18nMetadata:
      type: object
      required:
        - languages
        - language
        - translations
      properties:
        languages:
          type: array
          items:
            type: string
          description: List of available languages
          example:
            - en
            - es
        language:
          type: string
          description: The language used for translations (defaults to 'en' if not
            specified)
          example: en
        totalResults:
          type: integer
          description: Total number of translation keys returned
          example: 3
        translations:
          type: object
          description: Translations organized by namespace
          additionalProperties:
            type: object
            additionalProperties:
              type: string
          example:
            auth:
              login.button: Login
              login.title: Welcome
    Member:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - user
            - group
        display:
          type: string
          readOnly: true
          description: Display name of the member (only included when include=display
            query parameter is used). For users, resolved from the
            schema-configured display attribute (`systemAttributes.display`);
            falls back to the user ID if the attribute is not configured, the
            path does not exist, or the value is empty. For groups, the group
            name is used.
    Group:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        ouId:
          type: string
          format: uuid
        ouHandle:
          type: string
          readOnly: true
          description: Human-readable handle of the organization unit (only included when
            include=display query parameter is used).
    CreateGroupRequest:
      type: object
      required:
        - name
        - ouId
      properties:
        name:
          type: string
        description:
          type: string
        ouId:
          type: string
          format: uuid
        members:
          type: array
          items:
            $ref: "#/components/schemas/Member"
    UpdateGroupRequest:
      type: object
      required:
        - name
        - ouId
      properties:
        name:
          type: string
        description:
          type: string
        ouId:
          type: string
          format: uuid
    GroupListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 8
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 5
        groups:
          type: array
          items:
            $ref: "#/components/schemas/Group"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    MemberListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 20
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 10
        members:
          type: array
          items:
            $ref: "#/components/schemas/Member"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    CreateGroupByPathRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The display name of the group
          example: Sports Team
        description:
          type: string
          description: Optional description of the group
          example: Group for sports activities and events
        members:
          type: array
          description: Optional list of initial members (users and groups)
          items:
            $ref: "#/components/schemas/Member"
    MembersRequest:
      type: object
      required:
        - members
      properties:
        members:
          type: array
          description: List of members to add or remove
          minItems: 1
          items:
            $ref: "#/components/schemas/Member"
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum:
            - UP
            - DOWN
            - UNKNOWN
        serviceStatus:
          type: array
          items:
            type: object
            properties:
              serviceName:
                type: string
                enum:
                  - ConfigDB
                  - RuntimeDB
                  - UserDB
              status:
                type: string
                enum:
                  - UP
                  - DOWN
                  - UNKNOWN
    LanguageListResponse:
      type: object
      required:
        - languages
      properties:
        languages:
          type: array
          items:
            type: string
          description: List of language tags available in the system.
          example:
            - en
            - es
            - fr
            - fr-CA
    TranslationResponse:
      type: object
      description: Single translation response.
      required:
        - language
        - namespace
        - key
        - value
      properties:
        language:
          type: string
          description: Language tag.
          example: es
        namespace:
          type: string
          description: Namespace of the translation.
          example: errors
        key:
          type: string
          description: Translation key.
          example: user.not_found
        value:
          type: string
          description: Translated value.
          example: Usuario no encontrado
    SetTranslationRequest:
      type: object
      description: Request to set a single translation.
      required:
        - value
      properties:
        value:
          type: string
          description: Translation value.
          minLength: 1
          maxLength: 4096
          example: Usuario no encontrado
    LanguageTranslationsResponse:
      type: object
      description: All translations for a language, organized by namespace.
      required:
        - language
        - translations
      properties:
        language:
          type: string
          description: Language tag.
          example: es
        totalResults:
          type: integer
          description: Total number of translation keys returned.
          example: 5
        translations:
          type: object
          description: Translations organized by namespace.
          additionalProperties:
            type: object
            additionalProperties:
              type: string
          example:
            auth:
              login.button: Iniciar sesión
              login.title: Bienvenido
            errors:
              user.not_found: Usuario no encontrado
    SetTranslationsRequest:
      type: object
      description: Request to set custom translations for a language.
      required:
        - translations
      properties:
        translations:
          type: object
          description: Translations organized by namespace.
          additionalProperties:
            type: object
            additionalProperties:
              type: string
          example:
            auth:
              login.button: Iniciar sesión
              login.title: Bienvenido
              logout.button: Cerrar sesión
            errors:
              user.not_found: Usuario no encontrado
              invalid.input: Entrada inválida
    I18nMessage:
      type: object
      description: Internationalized message with translation key and default value.
      required:
        - key
        - defaultValue
      properties:
        key:
          type: string
          description: Translation key for fetching localized message.
          example: error.i18nservice.missing_language
        defaultValue:
          type: string
          description: Default message in English (fallback).
          example: Missing language code
    IDPRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Name of the identity provider
          example: Google
        description:
          type: string
          description: Description of the identity provider
          example: Google OIDC identity provider for employee authentication
        type:
          type: string
          description: Type of the identity provider (e.g., OAUTH)
          example: GOOGLE
          enum:
            - OAUTH
            - OIDC
            - GOOGLE
            - GITHUB
        properties:
          type: array
          items:
            $ref: "#/components/schemas/IDPProperty"
          description: Properties of the identity provider
          example:
            - name: client_id
              value: your-client-id
              isSecret: false
            - name: client_secret
              value: your-client-secret
              isSecret: true
            - name: scope
              value: openid email profile
              isSecret: false
    IDPResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the identity provider
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Name of the identity provider
          example: Google
        description:
          type: string
          description: Description of the identity provider
          example: Google OIDC identity provider for employee authentication
        type:
          type: string
          description: Type of the identity provider (e.g., OAUTH)
          example: GOOGLE
          enum:
            - OAUTH
            - OIDC
            - GOOGLE
            - GITHUB
        properties:
          type: array
          items:
            $ref: "#/components/schemas/IDPProperty"
          description: Properties of the identity provider
          example:
            - name: client_id
              value: your-client-id
              isSecret: false
            - name: client_secret
              value: "******"
              isSecret: true
            - name: scope
              value: openid email profile
              isSecret: false
    BasicIDPResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the identity provider
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Name of the identity provider
          example: Google
        description:
          type: string
          description: Description of the identity provider
          example: Google OIDC identity provider for employee authentication
        type:
          type: string
          description: Type of the identity provider (e.g., OAUTH)
          example: GOOGLE
          enum:
            - OAUTH
            - OIDC
            - GOOGLE
            - GITHUB
    IDPListResponse:
      type: array
      items:
        $ref: "#/components/schemas/BasicIDPResponse"
      example:
        - id: 550e8400-e29b-41d4-a716-446655440000
          name: Google
          description: Google OIDC identity provider for employee authentication
          type: GOOGLE
        - id: 660e8400-e29b-41d4-a716-446655440001
          name: GitHub
          description: GitHub OAuth identity provider for developer authentication
          type: GITHUB
    IDPProperty:
      type: object
      properties:
        name:
          type: string
          description: Name of the property
          example: your-client-id
        value:
          type: string
          description: Value of the property
          example: your-client-id
        isSecret:
          type: boolean
          description: Whether the property is secret
          example: false
    MessageNotificationSenderList:
      type: array
      description: List of message notification senders
      items:
        $ref: "#/components/schemas/MessageNotificationSenderResponse"
    MessageNotificationSenderResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the message notification sender
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Name of the message notification sender
          example: Twilio SMS Sender
        description:
          type: string
          description: Description of the message notification sender
          example: Sender for sending SMS messages using Twilio
        provider:
          type: string
          description: Provider of the message notification sender
          enum:
            - twilio
            - vonage
            - custom
          example: twilio
        properties:
          type: array
          description: Properties of the message notification sender
          items:
            type: object
            properties:
              name:
                type: string
                description: Property name
                example: account_sid
              value:
                type: string
                description: Property value (masked with ****** for secret properties)
                example: ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
              isSecret:
                type: boolean
                description: Indicates if the property is a secret
                example: true
    MessageNotificationSender:
      type: object
      properties:
        name:
          type: string
          description: Name of the message notification sender
          example: Twilio SMS Sender
        description:
          type: string
          description: Description of the message notification sender
          example: Sender for sending SMS messages using Twilio
        provider:
          type: string
          description: Provider of the message notification sender
          enum:
            - twilio
            - vonage
            - custom
          example: twilio
        properties:
          type: array
          description: Properties of the message notification sender
          items:
            type: object
            properties:
              name:
                type: string
                description: Property name
                example: account_sid
              value:
                type: string
                description: Property value
                example: ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
              isSecret:
                type: boolean
                description: Indicates if the property is a secret
                example: true
      required:
        - name
        - type
        - provider
    OrganizationUnitBasic:
      type: object
      required:
        - id
        - handle
        - name
      properties:
        id:
          type: string
          format: uuid
        handle:
          type: string
        name:
          type: string
        description:
          type: string
        logoUrl:
          type: string
          format: uri
          description: Logo URL for the organization unit
    OrganizationUnit:
      allOf:
        - $ref: "#/components/schemas/OrganizationUnitBasic"
      properties:
        parent:
          type: string
          format: uuid
          nullable: true
    User:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
        ouId:
          type: string
          format: uuid
        ouHandle:
          type: string
          readOnly: true
          description: Human-readable handle of the organization unit (only included when
            include=display query parameter is used).
        type:
          type: string
        attributes:
          type: object
          additionalProperties: true
        display:
          type: string
          readOnly: true
          description: Display name of the user (only included when include=display query
            parameter is used). Resolved from the schema-configured display
            attribute (`systemAttributes.display`). Falls back to the user ID if
            no display attribute is configured, the configured attribute path
            does not exist in the user's data, or the attribute value is empty.
    CreateOrganizationUnitByHandleRequest:
      type: object
      required:
        - handle
        - name
      properties:
        handle:
          type: string
          description: The unique handle for the organization unit within its parent
          example: frontend-dev
        name:
          type: string
          description: The display name of the organization unit
          example: Frontend Development Team
        description:
          type: string
          description: Optional description of the organization unit
          example: Team responsible for frontend development and UI/UX
        themeId:
          type: string
          format: uuid
          description: Theme configuration ID for the organization unit
        layoutId:
          type: string
          format: uuid
          description: Layout configuration ID for the organization unit
        logoUrl:
          type: string
          format: uri
          description: Logo URL for the organization unit
        tosUri:
          type: string
          format: uri
          description: Terms of Service URI
        policyUri:
          type: string
          format: uri
          description: Privacy Policy URI
        cookiePolicyUri:
          type: string
          format: uri
          description: Cookie Policy URI
    UpdateOrganizationUnitByHandleRequest:
      type: object
      required:
        - name
        - handle
      properties:
        name:
          type: string
          description: The display name of the organization unit
          example: Frontend Development Team
        handle:
          type: string
          description: The unique handle for the organization unit within its parent
          example: frontend-dev
        description:
          type: string
          description: Optional description of the organization unit
          example: Team responsible for frontend development and UI/UX
        themeId:
          type: string
          format: uuid
          description: Theme configuration ID for the organization unit
        layoutId:
          type: string
          format: uuid
          description: Layout configuration ID for the organization unit
        logoUrl:
          type: string
          format: uri
          description: Logo URL for the organization unit
        tosUri:
          type: string
          format: uri
          description: Terms of Service URI
        policyUri:
          type: string
          format: uri
          description: Privacy Policy URI
        cookiePolicyUri:
          type: string
          format: uri
          description: Cookie Policy URI
    CreateOrganizationUnitRequest:
      allOf:
        - $ref: "#/components/schemas/CreateOrganizationUnitByHandleRequest"
      required:
        - handle
        - name
        - parent
      properties:
        parent:
          type: string
          format: uuid
          nullable: true
    UpdateOrganizationUnitRequest:
      allOf:
        - $ref: "#/components/schemas/CreateOrganizationUnitRequest"
    OrganizationUnitListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 15
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 10
        organizationUnits:
          type: array
          items:
            $ref: "#/components/schemas/OrganizationUnitBasic"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    UserListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 25
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 10
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    PasskeyRegistrationStartRequest:
      type: object
      properties:
        userId:
          type: string
          description: User ID of the user to register credentials for
          example: 550e8400-e29b-41d4-a716-446655440000
        relyingPartyId:
          type: string
          description: Relying Party ID (typically the domain)
          example: example.com
        relyingPartyName:
          type: string
          description: Human-readable name for the Relying Party
          example: Example Corp
        authenticatorSelection:
          type: object
          description: Criteria for selecting authenticators
          properties:
            authenticatorAttachment:
              type: string
              description: Authenticator attachment modality
              enum:
                - platform
                - cross-platform
              example: platform
            requireResidentKey:
              type: boolean
              description: Whether a resident key is required
              example: false
            residentKey:
              type: string
              description: Resident key requirement
              enum:
                - discouraged
                - preferred
                - required
              example: preferred
            userVerification:
              type: string
              description: User verification requirement
              enum:
                - required
                - preferred
                - discouraged
              example: preferred
        attestation:
          type: string
          description: Attestation conveyance preference
          enum:
            - none
            - indirect
            - direct
            - enterprise
          example: none
      required:
        - userId
        - relyingPartyId
    PasskeyRegistrationStartResponse:
      type: object
      properties:
        publicKeyCredentialCreationOptions:
          type: object
          description: PublicKeyCredentialCreationOptions as per WebAuthn standard
          properties:
            challenge:
              type: string
              description: Base64url-encoded challenge for the registration ceremony
              example: Z29yZG9uQGV4YW1wbGUuY29tMjAyMS0wMy0xMlQxMjo0NTowMFo
            rp:
              type: object
              description: Relying Party information
              properties:
                id:
                  type: string
                  description: Relying Party identifier
                  example: example.com
                name:
                  type: string
                  description: Human-readable Relying Party name
                  example: Example Corp
              required:
                - id
                - name
            user:
              type: object
              description: User information for the credential
              properties:
                id:
                  type: string
                  description: Base64url-encoded user handle
                  example: NTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAw
                name:
                  type: string
                  description: User's username or email
                  example: gordon@example.com
                displayName:
                  type: string
                  description: User's display name
                  example: Gordon Freeman
              required:
                - id
                - name
                - displayName
            pubKeyCredParams:
              type: array
              description: Supported public key algorithms
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of credential
                    example: public-key
                  alg:
                    type: integer
                    description: COSE algorithm identifier
                    example: -7
              example:
                - type: public-key
                  alg: -7
                - type: public-key
                  alg: -257
            timeout:
              type: integer
              description: Time in milliseconds that the user has to respond to the prompt
              example: 60000
            excludeCredentials:
              type: array
              description: Credentials to exclude from registration
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of the credential
                    example: public-key
                  id:
                    type: string
                    description: Base64url-encoded credential ID
                    example: AdC-ff_z-Z1gY2s6e_2A-g
                  transports:
                    type: array
                    description: Hints about where the credential might be stored
                    items:
                      type: string
                      enum:
                        - usb
                        - nfc
                        - ble
                        - internal
                        - hybrid
            authenticatorSelection:
              type: object
              description: Criteria for authenticator selection
              properties:
                authenticatorAttachment:
                  type: string
                  enum:
                    - platform
                    - cross-platform
                  example: platform
                requireResidentKey:
                  type: boolean
                  example: false
                residentKey:
                  type: string
                  enum:
                    - discouraged
                    - preferred
                    - required
                  example: preferred
                userVerification:
                  type: string
                  enum:
                    - required
                    - preferred
                    - discouraged
                  example: preferred
            attestation:
              type: string
              description: Attestation conveyance preference
              enum:
                - none
                - indirect
                - direct
                - enterprise
              example: none
          required:
            - challenge
            - rp
            - user
            - pubKeyCredParams
          example:
            challenge: Z29yZG9uQGV4YW1wbGUuY29tMjAyMS0wMy0xMlQxMjo0NTowMFo
            rp:
              id: example.com
              name: Example Corp
            user:
              id: NTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAw
              name: gordon@example.com
              displayName: Gordon Freeman
            pubKeyCredParams:
              - type: public-key
                alg: -7
              - type: public-key
                alg: -257
            timeout: 60000
            authenticatorSelection:
              authenticatorAttachment: platform
              requireResidentKey: false
              residentKey: preferred
              userVerification: preferred
            attestation: none
        sessionToken:
          type: string
          description: JWT token for the WebAuthn registration session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      required:
        - publicKeyCredentialCreationOptions
        - sessionToken
    PasskeyRegistrationFinishRequest:
      type: object
      properties:
        publicKeyCredential:
          type: object
          description: PublicKeyCredential as per Passkey standard
          properties:
            id:
              type: string
              description: Base64url-encoded credential ID
              example: AdC-ff_z-Z1gY2s6e_2A-g
            rawId:
              type: string
              description: Base64url-encoded raw credential ID
              example: AdC-ff_z-Z1gY2s6e_2A-g
            type:
              type: string
              description: Type of the credential
              example: public-key
            response:
              type: object
              description: AuthenticatorAttestationResponse
              properties:
                clientDataJSON:
                  type: string
                  description: Base64url-encoded client data JSON
                  example: eyJjaGFsbGVuZ2UiOiJaMm95Wm05eVpHOXVRR1Y0WVcxd2JHVXVZMjl0TWpBeU1TMHdNeTB4TWxSeE1qbzBOVG93TUZvIiwidHlwZSI6IndlYmF1dGhuLmNyZWF0ZSIsIm9yaWdpbiI6Imh0dHBzOi8vZXhhbXBsZS5jb20ifQ
                attestationObject:
                  type: string
                  description: Base64url-encoded attestation object
                  example: o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVkBZ0mWDeWIDoxodDQXD2R2YFuP5K65ooYyx5lc87qDHZdjRQAAAAA
                transports:
                  type: array
                  description: Available transports for this credential
                  items:
                    type: string
                    enum:
                      - usb
                      - nfc
                      - ble
                      - internal
                      - hybrid
                  example:
                    - internal
                    - hybrid
              required:
                - clientDataJSON
                - attestationObject
            authenticatorAttachment:
              type: string
              description: Authenticator attachment modality
              enum:
                - platform
                - cross-platform
              example: platform
          required:
            - id
            - rawId
            - type
            - response
          example:
            id: AdC-ff_z-Z1gY2s6e_2A-g
            rawId: AdC-ff_z-Z1gY2s6e_2A-g
            type: public-key
            response:
              clientDataJSON: eyJjaGFsbGVuZ2UiOiJaMm95Wm05eVpHOXVRR1Y0WVcxd2JHVXVZMjl0TWpBeU1TMHdNeTB4TWxSeE1qbzBOVG93TUZvIiwidHlwZSI6IndlYmF1dGhuLmNyZWF0ZSIsIm9yaWdpbiI6Imh0dHBzOi8vZXhhbXBsZS5jb20ifQ
              attestationObject: o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVkBZ0mWDeWIDoxodDQXD2R2YFuP5K65ooYyx5lc87qDHZdjRQAAAAA
              transports:
                - internal
                - hybrid
            authenticatorAttachment: platform
        sessionToken:
          type: string
          description: JWT token for the Passkey registration session
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        credentialName:
          type: string
          description: User-friendly name for the credential
          example: My iPhone
      required:
        - publicKeyCredential
        - sessionToken
    PasskeyRegistrationFinishResponse:
      type: object
      properties:
        credentialId:
          type: string
          description: The unique identifier of the registered credential
          example: AdC-ff_z-Z1gY2s6e_2A-g
        credentialName:
          type: string
          description: User-friendly name for the credential
          example: My iPhone
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the credential was created
          example: 2024-01-15T10:30:00Z
      required:
        - credentialId
    ResourceServer:
      type: object
      required:
        - id
        - name
        - ouId
        - delimiter
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the resource server
        name:
          type: string
          description: Name of the resource server
        description:
          type: string
          nullable: true
          description: Optional description of the resource server
        identifier:
          type: string
          nullable: true
          description: Optional identifier for authorization requests (Unique in the
            system if provided)
        ouId:
          type: string
          format: uuid
          description: ID of the organization unit this resource server belongs to
        delimiter:
          type: string
          description: Character used to separate permission hierarchy levels (immutable
            after creation)
    CreateResourceServerRequest:
      type: object
      required:
        - name
        - ouId
      properties:
        name:
          type: string
          description: Name of the resource server
        description:
          type: string
          description: Optional description of the resource server
        identifier:
          type: string
          description: Optional identifier for authorization requests (Unique in the
            system if provided)
        ouId:
          type: string
          format: uuid
          description: ID of the organization unit this resource server belongs to
        delimiter:
          type: string
          description: Optional delimiter character for permission hierarchy (defaults to
            ":", immutable after creation)
    UpdateResourceServerRequest:
      type: object
      required:
        - name
        - ouId
      properties:
        name:
          type: string
          description: Name of the resource server
        description:
          type: string
          description: Optional description of the resource server
        identifier:
          type: string
          description: Optional identifier for authorization requests (Unique in the
            system if provided)
        ouId:
          type: string
          format: uuid
          description: ID of the organization unit this resource server belongs to
    Resource:
      type: object
      required:
        - id
        - name
        - handle
        - permission
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the resource
        name:
          type: string
          description: Display name of the resource
        handle:
          type: string
          description: Immutable and unique under resource server or parent resource.
            Identifier used for permission derivation
        description:
          type: string
          nullable: true
          description: Optional description of the resource
        parent:
          type: string
          format: uuid
          nullable: true
          description: Parent resource ID (null for top-level resources, immutable after
            creation)
        permission:
          type: string
          description: Derived permission string based on handle hierarchy
    CreateResourceRequest:
      type: object
      required:
        - name
        - handle
      properties:
        name:
          type: string
          description: Display name of the resource
        handle:
          type: string
          description: Immutable and unique under resource server or parent resource.
            Identifier used for permission derivation
        description:
          type: string
          description: Optional description of the resource
        parent:
          type: string
          format: uuid
          nullable: true
          description: Parent resource ID (null for top-level resources, immutable after
            creation)
    UpdateResourceRequest:
      type: object
      properties:
        name:
          type: string
          description: Display name of the resource (mutable)
        description:
          type: string
          description: Optional description of the resource
    CreateActionRequest:
      type: object
      required:
        - name
        - handle
      properties:
        name:
          type: string
          description: Display name of the action
        handle:
          type: string
          description: Immutable and unique under resource server or resource. Identifier
            used for permission derivation
        description:
          type: string
          description: Optional description of the action
    UpdateActionRequest:
      type: object
      properties:
        name:
          type: string
          description: Display name of the action
        description:
          type: string
          description: Optional description of the action
    ResourceServerListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation
          example: 8
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page
          example: 5
        resourceServers:
          type: array
          items:
            $ref: "#/components/schemas/ResourceServer"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    ResourceListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation
          example: 15
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page
          example: 10
        resources:
          type: array
          items:
            $ref: "#/components/schemas/Resource"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    ActionListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation
          example: 12
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page
          example: 10
        actions:
          type: array
          items:
            $ref: "#/components/schemas/Action"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    Assignment:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: ID of the user or group being assigned
        type:
          type: string
          enum:
            - user
            - group
          description: Type of entity being assigned (user or group)
        display:
          type: string
          readOnly: true
          description: Display name of the user or group (only included when
            include=display query parameter is used). For users, resolved from
            the schema-configured display attribute; falls back to the user ID
            if the attribute is not configured, the path does not exist, or the
            value is empty. For groups, the group name is used.
    AssignmentInput:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: ID of the user or group being assigned
        type:
          type: string
          enum:
            - user
            - group
          description: Type of entity being assigned (user or group)
    ResourcePermissions:
      type: object
      required:
        - resourceServerId
        - permissions
      properties:
        resourceServerId:
          type: string
          format: uuid
          description: ID of the resource server these permissions belong to
        permissions:
          type: array
          items:
            type: string
          description: List of permission strings for this resource server
    RoleSummary:
      type: object
      required:
        - id
        - name
        - ouId
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the role
        name:
          type: string
          description: Name of the role
        description:
          type: string
          nullable: true
          description: Optional description of the role
        ouId:
          type: string
          format: uuid
          description: ID of the organization unit this role belongs to
    Role:
      type: object
      required:
        - id
        - name
        - ouId
        - permissions
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the role
        name:
          type: string
          description: Name of the role
        description:
          type: string
          nullable: true
          description: Optional description of the role
        ouId:
          type: string
          format: uuid
          description: ID of the organization unit this role belongs to
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/ResourcePermissions"
          description: List of resource permissions grouped by resource server
    RoleWithAssignments:
      allOf:
        - $ref: "#/components/schemas/Role"
        - type: object
          properties:
            assignments:
              type: array
              items:
                $ref: "#/components/schemas/Assignment"
              description: List of user and group assignments with display names
    CreateRoleRequest:
      type: object
      required:
        - name
        - ouId
      properties:
        name:
          type: string
          description: Name of the role
        description:
          type: string
          description: Optional description of the role
        ouId:
          type: string
          format: uuid
          description: ID of the organization unit this role belongs to
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/ResourcePermissions"
          description: Optional list of initial permissions grouped by resource server
        assignments:
          type: array
          items:
            $ref: "#/components/schemas/AssignmentInput"
          description: Optional list of initial user and group assignments
    UpdateRoleRequest:
      type: object
      required:
        - name
        - ouId
        - permissions
      properties:
        name:
          type: string
          description: Name of the role
        description:
          type: string
          description: Optional description of the role
        ouId:
          type: string
          format: uuid
          description: ID of the organization unit this role belongs to
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/ResourcePermissions"
          description: List of resource permissions grouped by resource server
    AssignmentsRequest:
      type: object
      required:
        - assignments
      properties:
        assignments:
          type: array
          items:
            $ref: "#/components/schemas/AssignmentInput"
          description: List of user and group assignments
    RoleListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 8
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 5
        roles:
          type: array
          items:
            $ref: "#/components/schemas/RoleSummary"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    AssignmentListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 20
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 10
        assignments:
          type: array
          items:
            $ref: "#/components/schemas/Assignment"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    UserGroup:
      type: object
      required:
        - id
        - name
        - ouId
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the group
        name:
          type: string
          description: The name of the group
        ouId:
          type: string
          format: uuid
          description: The organization unit ID that the group belongs to
    UserGroupListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 8
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 5
        groups:
          type: array
          items:
            $ref: "#/components/schemas/UserGroup"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    CreateUserByPathRequest:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The type of user
          example: employee
        groups:
          type: array
          description: List of groups that the user should belong to
          items:
            type: string
            format: uuid
            description: Group ID
        attributes:
          type: object
          description: User attributes
          additionalProperties: true
          example:
            username: john.doe
            firstname: John
            lastname: Doe
            email: john.doe@company.com
            department: Engineering
    CreateUserRequest:
      type: object
      required:
        - ouId
        - type
      properties:
        ouId:
          type: string
          format: uuid
          description: The organization unit ID where the user will be created
        type:
          type: string
          description: The type of user
          example: customer
        groups:
          type: array
          description: List of groups that the user should belong to
          items:
            type: string
            format: uuid
            description: Group ID
        attributes:
          type: object
          description: User attributes
          additionalProperties: true
    UpdateUserRequest:
      type: object
      properties:
        ouId:
          type: string
          format: uuid
          description: The organization unit ID where the user belongs
        type:
          type: string
          description: The type of user
        groups:
          type: array
          description: List of groups that the user should belong to
          items:
            type: string
            format: uuid
            description: Group ID
        attributes:
          type: object
          description: User attributes
          additionalProperties: true
    UpdateSelfUserRequest:
      type: object
      required:
        - attributes
      properties:
        attributes:
          type: object
          description: User attributes
          additionalProperties: true
    UserSchema:
      type: object
      required:
        - id
        - name
        - ouId
        - schema
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the user schema
        name:
          type: string
          description: The user type this schema defines
        ouId:
          type: string
          format: uuid
          description: The root organization unit ID associated with this user type schema
        ouHandle:
          type: string
          readOnly: true
          description: Human-readable handle of the organization unit (only included when
            include=display query parameter is used).
        allowSelfRegistration:
          type: boolean
          description: Indicates whether users of this type can perform self-registration
            flows
          default: false
        systemAttributes:
          type: object
          description: System-level metadata for the user schema
          properties:
            display:
              type: string
              description: The schema attribute to use as the human-readable display name for
                users of this type
          additionalProperties: false
        schema:
          type: object
          description: JSON Schema definition for the user type
          additionalProperties:
            oneOf:
              - type: object
                description: Leaf property - string or number
                required:
                  - type
                properties:
                  type:
                    type: string
                    enum:
                      - string
                      - number
                    description: Data type of the property
                  required:
                    type: boolean
                    default: false
                    description: Whether this attribute must be provided for the user type
                  unique:
                    type: boolean
                    default: false
                    description: Whether this property must be unique across all users
                  credential:
                    type: boolean
                    default: false
                    description: Whether this property should be treated as a credential attribute
                  enum:
                    type: array
                    items:
                      type: string
                    description: List of allowed values for this property
                  regex:
                    type: string
                    description: Regular expression pattern for validating the property value
                additionalProperties: false
              - type: object
                description: Leaf property - boolean
                required:
                  - type
                properties:
                  type:
                    type: string
                    enum:
                      - boolean
                    description: Data type of the property
                  required:
                    type: boolean
                    default: false
                    description: Whether this attribute must be provided for the user type
                additionalProperties: false
              - type: object
                description: Object property definition
                required:
                  - type
                  - properties
                properties:
                  type:
                    type: string
                    enum:
                      - object
                    description: Data type (object)
                  required:
                    type: boolean
                    default: false
                    description: Whether this attribute must be provided for the user type
                  properties:
                    type: object
                    description: Nested properties of the object
                    additionalProperties:
                      $ref: "#/components/schemas/UserSchema/properties/schema/additionalProperties"
                additionalProperties: false
              - type: object
                description: Array property definition
                required:
                  - type
                  - items
                properties:
                  type:
                    type: string
                    enum:
                      - array
                    description: Data type (array)
                  required:
                    type: boolean
                    default: false
                    description: Whether this attribute must be provided for the user type
                  items:
                    oneOf:
                      - type: object
                        description: Array of strings or numbers
                        required:
                          - type
                        properties:
                          type:
                            type: string
                            enum:
                              - string
                              - number
                          enum:
                            type: array
                            items:
                              type: string
                        additionalProperties: false
                      - type: object
                        description: Array of booleans
                        required:
                          - type
                        properties:
                          type:
                            type: string
                            enum:
                              - boolean
                        additionalProperties: false
                      - type: object
                        description: Array of objects
                        required:
                          - type
                          - properties
                        properties:
                          type:
                            type: string
                            enum:
                              - object
                          properties:
                            type: object
                            additionalProperties:
                              $ref: "#/components/schemas/UserSchema/properties/schema/additionalProperties"
                        additionalProperties: false
                additionalProperties: false
          example:
            email:
              type: string
              required: true
              unique: true
              regex: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
            password:
              type: string
              required: true
              credential: true
              regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]).{8,}$
            age:
              type: number
            isActive:
              type: boolean
            phoneNumber:
              type: string
              regex: ^\+?[1-9]\d{1,14}$
            role:
              type: string
              enum:
                - admin
                - user
                - guest
            address:
              type: object
              required: true
              properties:
                street:
                  type: string
                city:
                  type: string
                  required: true
                zipCode:
                  type: string
                  regex: ^\d{5}(-\d{4})?$
            tags:
              type: array
              items:
                type: string
                enum:
                  - vip
                  - premium
                  - standard
    UserSchemaListResponse:
      type: object
      properties:
        totalResults:
          type: integer
          description: Number of results that match the listing operation.
          example: 5
        startIndex:
          type: integer
          description: Index of the first element of the page, which will be equal to
            offset + 1.
          example: 1
        count:
          type: integer
          description: Number of elements in the returned page.
          example: 3
        schemas:
          type: array
          items:
            type: object
            required:
              - id
              - name
              - ouId
            properties:
              id:
                type: string
                format: uuid
                description: The unique identifier of the user schema
              name:
                type: string
                description: The user type this schema defines
              ouId:
                type: string
                format: uuid
                description: The root organization unit ID associated with this user type schema
              ouHandle:
                type: string
                readOnly: true
                description: Human-readable handle of the organization unit (only included when
                  include=display query parameter is used).
              allowSelfRegistration:
                type: boolean
                description: Indicates whether users of this type can perform self-registration
                  flows
                default: false
              systemAttributes:
                type: object
                description: System-level metadata for the user schema
                properties:
                  display:
                    type: string
                    description: The schema attribute to use as the human-readable display name for
                      users of this type
                additionalProperties: false
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    CreateUserSchemaRequest:
      type: object
      required:
        - name
        - ouId
        - schema
      properties:
        name:
          type: string
          description: The user type this schema will define
        ouId:
          type: string
          format: uuid
          description: The organization unit ID where this user type schema is applicable
        allowSelfRegistration:
          type: boolean
          description: Whether the user type supports user-initiated registration
          default: false
        systemAttributes:
          $ref: "#/components/schemas/UserSchema/properties/systemAttributes"
        schema:
          type: object
          description: JSON Schema definition for the user type
          additionalProperties:
            $ref: "#/components/schemas/UserSchema/properties/schema/additionalProperties"
    UpdateUserSchemaRequest:
      type: object
      required:
        - name
        - ouId
        - schema
      properties:
        name:
          type: string
          description: The user type this schema defines
        ouId:
          type: string
          format: uuid
          description: The root organization unit ID where this user type schema is
            applicable
        allowSelfRegistration:
          type: boolean
          description: Whether the user type supports user-initiated registration
          default: false
        systemAttributes:
          $ref: "#/components/schemas/UserSchema/properties/systemAttributes"
        schema:
          type: object
          description: JSON Schema definition for the user type
          additionalProperties:
            $ref: "#/components/schemas/UserSchema/properties/schema/additionalProperties"
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://localhost:8090/oauth2/authorize
          tokenUrl: https://localhost:8090/oauth2/token
          scopes:
            system: Access to system management APIs
  responses:
    BadRequest:
      description: Bad request - Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            invalid-language:
              summary: Invalid language tag format
              value:
                code: I18N-1001
                message:
                  key: error.i18nservice.invalid_language
                  defaultValue: Invalid language tag format
                description:
                  key: error.i18nservice.invalid_language_description
                  defaultValue: The language tag must follow BCP 47 format (e.g., 'en', 'es',
                    'fr-CA')
            invalid-namespace:
              summary: Invalid namespace format
              value:
                code: I18N-1002
                message:
                  key: error.i18nservice.invalid_namespace
                  defaultValue: Invalid namespace format
                description:
                  key: error.i18nservice.invalid_namespace_description
                  defaultValue: The namespace can only contain alphanumeric characters,
                    underscores, and hyphens
            invalid-key:
              summary: Invalid key format
              value:
                code: I18N-1003
                message:
                  key: error.i18nservice.invalid_key
                  defaultValue: Invalid key format
                description:
                  key: error.i18nservice.invalid_key_description
                  defaultValue: The key can only contain alphanumeric characters, dots,
                    underscores, and hyphens
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: AUTH-4001
            message:
              key: error.auth.unauthorized
              defaultValue: Unauthorized
            description:
              key: error.auth.unauthorized_description
              defaultValue: Authentication is required to access this resource
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: I18N-1006
            message:
              key: error.i18nservice.translation_not_found
              defaultValue: Translation not found
            description:
              key: error.i18nservice.translation_not_found_description
              defaultValue: The requested translation does not exist for the specified
                language, namespace, and key
    Conflict:
      description: Conflict - resource cannot be deleted as it's in use
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: THM-1004
            message: Cannot delete theme
            description: Cannot delete theme configuration that is currently associated with
              one or more applications
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: I18N-5000
            message:
              key: error.i18nservice.internal_server_error
              defaultValue: Internal server error
            description:
              key: error.i18nservice.internal_server_error_description
              defaultValue: An unexpected error occurred while processing the request
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: AUTH-4003
            message:
              key: error.auth.forbidden
              defaultValue: Forbidden
            description:
              key: error.auth.forbidden_description
              defaultValue: You do not have permission to access this resource
  parameters:
    limitQueryParam:
      in: query
      name: limit
      required: false
      description: >
        Maximum number of records to return. Must be between 1 and 100 inclusive.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    offsetQueryParam:
      in: query
      name: offset
      required: false
      description: >
        Number of records to skip for pagination. Must be a non-negative integer.
      schema:
        type: integer
        minimum: 0
        default: 0
    idPathParam:
      name: id
      in: path
      description: The unique identifier
      required: true
      schema:
        type: string
        format: uuid
    includeQueryParam:
      in: query
      name: include
      required: false
      schema:
        type: string
        enum:
          - display
      description: >
        Optional parameter to include additional display information in the
        response. The exact fields included depend on the endpoint. See each
        endpoint's response schema for details on which fields are enriched.
    includeGroupQueryParam:
      in: query
      name: include
      required: false
      description: >
        Optional parameter to include additional display information.

        - `display` - Include `ouHandle`, the human-readable handle of the
        organization unit, alongside the `ouId`.
      schema:
        type: string
        enum:
          - display
    languagePathParam:
      name: language
      in: path
      required: true
      description: Language tag in BCP 47 format (e.g., `en`, `es`, `fr-CA`).
      schema:
        type: string
        pattern: ^[a-z]{2}(-[A-Z]{2})?(-[A-Za-z]+)?$
        example: es
    namespacePathParam:
      name: namespace
      in: path
      required: true
      description: Namespace for grouping translations (e.g., `auth`, `errors`, `common`).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_-]+$
        minLength: 1
        maxLength: 64
        example: errors
    keyPathParam:
      name: key
      in: path
      required: true
      description: Translation key within the namespace (e.g., `login.button`,
        `user.not_found`).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9._-]+$
        minLength: 1
        maxLength: 256
        example: user.not_found
    assigneeTypeQueryParam:
      in: query
      name: type
      required: false
      schema:
        type: string
        enum:
          - user
          - group
      description: >
        Filter assignments by assignee type. When omitted, assignments of all
        types are returned.
    filterParam:
      in: query
      name: filter
      required: false
      description: >
        Filter users by attribute values.

        Supported operators: eq (ie. equals).

        Format: `attribute operator "value"`.

        Examples:

        - `username eq "john.doe"` - Users with username = "john.doe"'

        - `age eq 25` - Users with age = 25

        - `address.city eq "Mountain View"` - Users with address.city =
        "Mountain View"
      schema:
        type: string
      examples:
        simple-string:
          summary: Simple string filter
          value: username eq "john.doe"
        simple-number:
          summary: Simple number filter
          value: age eq 25
        complex:
          summary: Complex filtering
          value: address.city eq "Mountain View"