openapi: 3.0.1
info:
  title: Jans Lock API
  contact:
    name: Contact
    url: https://github.com/JanssenProject/jans/discussions
  license:
    name: License
    url: https://github.com/JanssenProject/jans/blob/main/LICENSE
  version: OAS Version
servers:
- url: https://jans.local.io
  description: The Jans server
tags:
- name: Lock - Server Configuration
- name: Lock - Stat
- name: Lock - Audit Health
- name: Lock - Audit Log
- name: Lock - Audit Telemetry
paths:
  /api/v1/configuration:
    get:
      tags:
      - Lock - Server Configuration
      summary: Request .well-known data
      description: Request .well-know Lock server configuration
      operationId: getConfiguration
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                type: string
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
  /.well-known/lock-server-configuration:
    get:
      tags:
      - Lock - Server Configuration
      summary: Request .well-known data
      description: Request .well-know Lock server configuration
      operationId: doGet
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                type: string
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
  /api/v1/audit/health/bulk:
    post:
      tags:
      - Lock - Audit Health
      summary: Bulk save health data
      description: Bulk save health data
      operationId: processBulkHealthRequest
      requestBody:
        description: Bulk health entry
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/HealthEntry"
      responses:
        "200":
          description: Ok
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/health.write
  /api/v1/audit/log/bulk:
    post:
      tags:
      - Lock - Audit Log
      summary: Bulk save log data
      description: Bulk save log data
      operationId: processBulkLogRequest
      requestBody:
        description: Bulk log entry
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/LogEntry"
      responses:
        "200":
          description: Ok
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/log.write
  /api/v1/audit/telemetry/bulk:
    post:
      tags:
      - Lock - Audit Telemetry
      summary: Bulk save telemetry data
      description: Bulk save telemetry data
      operationId: processBulkTelemetryRequest
      requestBody:
        description: Bulk telemetry entry
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/TelemetryEntry"
      responses:
        "200":
          description: Ok
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/telemetry.write
  /api/v1/audit/health:
    post:
      tags:
      - Lock - Audit Health
      summary: Save health data
      description: Save health data
      operationId: processHealthRequest
      requestBody:
        description: Health entry
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HealthEntry"
      responses:
        "200":
          description: Ok
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/health.write
  /api/v1/audit/log:
    post:
      tags:
      - Lock - Audit Log
      summary: Save log data
      description: Save log data
      operationId: processLogRequest
      requestBody:
        description: Log entry
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LogEntry"
      responses:
        "200":
          description: Ok
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/log.write
  /api/v1/audit/telemetry:
    post:
      tags:
      - Lock - Audit Telemetry
      summary: Save telemetry data
      description: Save telemetry data
      operationId: processTelemetryRequest
      requestBody:
        description: Telemetry entry
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TelemetryEntry"
      responses:
        "200":
          description: Ok
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/telemetry.write
  /api/v1/policy:
    get:
      tags:
      - Lock - Policy
      summary: Request policies URI list
      description: Request policies URI list
      operationId: getPoliciesUriList
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/policy.readonly
  /api/v1/policy/{uri}:
    get:
      tags:
      - Lock - Policy
      summary: Request policy data
      description: Request policy data
      operationId: getPolicyByUri
      parameters:
      - name: uri
        in: path
        description: Policy URI
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/policy.readonly
  /api/v1/internal/stat:
    get:
      tags:
      - Lock - Stat
      summary: Request stat data
      description: Request stat data
      operationId: statGet
      parameters:
      - name: month
        in: query
        schema:
          type: string
      - name: start-month
        in: query
        schema:
          type: string
      - name: end-month
        in: query
        schema:
          type: string
      - name: format
        in: query
        schema:
          type: string
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlatStatResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "403":
          description: Future stat is disabled on server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/stat.readonly
    post:
      tags:
      - Lock - Stat
      summary: Request stat data
      description: Request stat data
      operationId: statPost
      requestBody:
        content:
          '*/*':
            schema:
              type: object
              properties:
                month:
                  type: string
                start-month:
                  type: string
                end-month:
                  type: string
                format:
                  type: string
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlatStatResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "401":
          description: Unauthorized
        "403":
          description: Future stat is disabled on server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
        "500":
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LockApiError"
      security:
      - oauth2:
        - https://jans.io/oauth/lock/stat.readonly
components:
  schemas:
    LockApiError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        description:
          type: string
    HealthEntry:
      type: object
      properties:
        dn:
          type: string
        baseDn:
          type: string
        inum:
          type: string
        creationDate:
          type: string
          description: Creation date of the entry
          format: date-time
          example: 2026-07-24T15:33:06.875Z
        eventTime:
          type: string
          description: Time when the event occurred
          format: date-time
          example: 2026-07-24T15:33:06.875Z
        service:
          type: string
          description: Service name
          example: Lock Server
        nodeName:
          type: string
          description: Node name or identifier
          example: 04bbe9ef-a853-417c-a2b8-5328b62936e2
        status:
          type: string
          description: Health status
          example: running
        engineStatus:
          type: object
          additionalProperties:
            type: string
      description: Health audit entry
    LogEntry:
      type: object
      properties:
        dn:
          type: string
        baseDn:
          type: string
        inum:
          type: string
        creationDate:
          type: string
          description: Creation date of the entry
          format: date-time
          example: 2026-07-24T15:33:02.937Z
        eventTime:
          type: string
          description: Time when the event occurred
          format: date-time
          example: 2026-07-24T15:33:02.937Z
        service:
          type: string
          description: Service name
          example: Lock Server
        nodeName:
          type: string
          description: Node name or identifier
          example: 04bbe9ef-a853-417c-a2b8-5328b62936e2
        eventType:
          type: string
          description: Type of event
          example: Decision
        severityLevel:
          type: string
          description: Severity level
          example: warning
          enum:
          - info
          - warning
          - error
          - critical
        action:
          type: string
          description: Action performed
          example: Jans::Action::"POST"
        decisionResult:
          type: string
          description: Decision result
          example: ALLOW
          enum:
          - ALLOW
          - DENY
        requestedResource:
          type: string
          description: Requested resource identifier
          example: Jans::HTTP_Request::"lock_audit_log_write"
        principalId:
          type: string
          description: Principal (user) identifier
          example: ACC0001
        clientId:
          type: string
          description: Client identifier
          example: CLI001
        jti:
          type: string
          description: JWT ID - unique identifier for the token
          example: 550e8400-e29b-41d4-a716-446655440000
        contextInformation:
          type: object
          additionalProperties:
            type: string
            description: Additional context information as key-value pairs
          description: Additional context information as key-value pairs
      description: Log audit entry
    TelemetryEntry:
      type: object
      properties:
        dn:
          type: string
        baseDn:
          type: string
        inum:
          type: string
        creationDate:
          type: string
          description: Creation date of the entry
          format: date-time
          example: 2026-07-24T15:33:06.872Z
        service:
          type: string
          description: Service name
          example: Lock Server
        nodeName:
          type: string
          description: Node name or identifier
          example: 04bbe9ef-a853-417c-a2b8-5328b62936e2
        status:
          type: string
          description: Service status
          example: running
        policyStats:
          type: object
          additionalProperties:
            type: integer
            description: Per-policy evaluation counters as key-value pairs
            format: int64
          description: Per-policy evaluation counters as key-value pairs
        errorCounters:
          type: object
          additionalProperties:
            type: integer
            description: Error counters broken down by error type
            format: int64
          description: Error counters broken down by error type
        operationalStats:
          type: object
          additionalProperties:
            type: integer
            description: "Operational statistics (requests, decisions, eval times)\
              \ as key-value pairs"
            format: int64
          description: "Operational statistics (requests, decisions, eval times) as\
            \ key-value pairs"
        intervalSecs:
          type: integer
          description: Telemetry collection interval in seconds
          format: int64
          example: 5
      description: Telemetry audit entry
    FlatStatResponse:
      type: object
      properties:
        response:
          type: array
          items:
            $ref: "#/components/schemas/StatResponseItem"
    StatResponseItem:
      type: object
      properties:
        month:
          type: string
        monthly_active_users:
          type: integer
          format: int64
        monthly_active_clients:
          type: integer
          format: int64
        operations_by_type:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: integer
              format: int64
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "https://{op-hostname}/.../token"
          scopes:
            https://jans.io/oauth/lock/policy.readonly: View policy related information
            https://jans.io/oauth/lock/health.write: Write audit health entries
            https://jans.io/oauth/lock/log.write: Write audit log entries
            https://jans.io/oauth/lock/telemetry.write: Write telemetry health entries
            https://jans.io/oauth/lock/stat.readonly: View stat related information