openapi: 3.1.0

info:
  title: Lithos ID API
  version: 1.0.0
  description: |
    REST API for identity verification using Government Identity Apps.

servers:
  - url: https://api.lithosid.com
    description: Production
  - url: https://api.test.lithosid.com
    description: Test

security:
  - bearerAuth: []

paths:
  /prove:
    post:
      summary: Start identity verification
      description: |
        Starts an identity verification flow.

        The response contains a URL to which the user should be redirected.
        After the user verifies their identity, Lithos ID sends a callback
        to your configured Redirect URL.

      operationId: proveIdentity

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProveRequest'

      responses:
        "200":
          description: Identity verification started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProveResponse'

        "400":
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        "401":
          description: Authentication or account error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

      callbacks:
        proofDelivered:
          '{$request.body#/redirect_url}':
            post:
              summary: Deliver cryptographic proof
              description: |
                After identity verification completes, Lithos ID sends a
                form-encoded POST request to the configured Redirect URL.

              requestBody:
                required: true
                content:
                  application/x-www-form-urlencoded:
                    schema:
                      oneOf:
                        - $ref: '#/components/schemas/ProofCallback'
                        - $ref: '#/components/schemas/ProofErrorCallback'

              responses:
                "200":
                  description: Callback accepted.
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/RedirectResponse'

  /health:
    get:
      summary: Health check
      operationId: health
      security: []

      responses:
        "200":
          description: API is healthy.

components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:

    ProveRequest:
      type: object
      required:
        - issuer
        - revealed
        - state

      properties:

        issuer:
          type: string
          description: Government Identity App identifier.
          example: xx-sandbox

        revealed:
          type: array
          description: PID attribute IDs already collected from the user.
          minItems: 1
          uniqueItems: true

          items:
            type: string
            enum:
              - family_name
              - given_name
              - birth_date
              - nationality

        state:
          type: string
          minLength: 1
          description: |
            Opaque value returned unchanged together with the proof.
          example: unique-state-id

        same_device:
          type: boolean
          default: false
          description: |
            Whether the Government Identity App should be opened on the
            same device.
          example: false

    ProveResponse:
      type: object
      required:
        - success
        - redirect_url

      properties:

        success:
          type: boolean
          const: true

        redirect_url:
          type: string
          format: uri
          description: URL to which the user should be redirected.

    ErrorResponse:
      type: object
      required:
        - success
        - error

      properties:

        success:
          type: boolean
          const: false

        error:
          $ref: '#/components/schemas/Error'

    Error:
      type: object
      required:
        - error
        - error_description

      properties:

        error:
          type: string
          example: error_missing_parameter

        error_description:
          type: string
          example: state is required

    ProofCallback:
      type: object
      required:
        - presentation
        - state

      properties:

        presentation:
          type: string
          description: Cryptographic proof.

        state:
          type: string

    ProofErrorCallback:
      type: object
      required:
        - error
        - error_description
        - state

      properties:

        error:
          type: string

        error_description:
          type: string

        state:
          type: string

    RedirectResponse:
      type: object
      required:
        - redirect_uri

      properties:

        redirect_uri:
          type: string
          format: uri
          description: URL to which Lithos ID should redirect the user's browser.