---
openapi: 3.0.0
info:
  title: Certifaction API
  version: "v1"
  x-logo:
    url: "certifaction_logo.svg"
    altText: Certifaction
  description: |
    # Quick Start

    In this guide we will show you how to register your
    first document using Certifaction API.
    In order not to be tied to a programming language we're going to show
    examples using [cURL](https://curl.haxx.se/). The API is served via HTTPS
    and any programming language supporting the HTTP protocol can be used.

    In this quick start, you will
    * create an account,
    * create an API token,
    * register your first document,
    * verify that your document was registered.

    ## Server endpoints
    We serve the API from two public endpoints, one for testing and one
    for production:

    - Testnet (Görli), 1000 free credits on `api.testnet.certifaction.io`
    - Mainnet, 10 free credits on `api.certifaction.io`

    We will use the testnet endpoint in the rest of this document and we
    recommend you to use it until you are confident enough.

    ## Create an account
    If you have not created a Certifaction account yet, please create in the
    Certifaction web application using one of the following URL:

    - Testnet (Görli): https://app.testnet.certifaction.io
    - Mainnet: https://app.certifaction.io

    You will need to confirm your email before being able to use the application.
    If you have not received it, please check your spam box.

    After creating your account, you are now ready to create your first API
    key.

    ## Create an API Key
    To create an API key on the Certifaction web application, please navigate
    to the API Key setting page using the upper right user account dropdown:

    *Settings* --> *API Keys* --> *New API Key*

    and follow the instructions.

    Please ensure that you copy the key and
    store it safely.  The key will give any holder the same account rights
    as yours.  The key is shown only once.  If you loose it, please remove it
    from the application and create a new one.

    Once you have an initial API key, you can create additional ones
    using the [token API](#operation/token-generate) endpoint.

    ## Register your first document
    To register a document, simply run the following cURL command replacing
    the file names in the `--data-binary` and `--output` parameters with your
    actual input and output files:

    ```
    curl -X POST --data-binary @example.pdf --output example-certified.pdf  -H "Authorization:<API key>" -H "Content-Type:application/pdf" https://api.testnet.certifaction.io/file/register?filename=test
    ```

    Please note that
    * we use the API key created in the previous step,
    * the `filename` parameter that we defined in the command will be
      referenced in the web application and
    * the registered document that has been returned in the response contains
      additional security data and needs to be saved with a different name.
      Only the new file containing the security data can be verified.

    At this point you successfully registered one file using our API.

    ## Verify your document

    ### Verify on the web
    * Open the verification page: https://app.testnet.certifaction.io/verification
    * Drag & drop the newly registered document.

    You should observe that the document was registered.  It can take several
    minutes before final registration to the blockchain.
    You can verify the document again later to know exactly in which
    blockchain transaction the document was recorded.

    ### Verify with the API
    You can also verify a document using the [verification API](#operation/verifyFile).

    # Authentication
    Certifaction API is accessible using an API key in the HTTP header:

    ```
    Authorization:<API key>
    ```

    For example, the following cURL command will return your user account
    information:

    ```
    curl -H "Authorization:<API key>" https://api.testnet.certifaction.io/user
    ```

    You can create API key in Certifaction web application as described in
    the [Quick Start](/#section/Quick-Start) section or by using the
    [token API](#operation/token-generate) endpoint.

    # HTTP Headers
    ## User-Agent

    If you integrate the Certifaction API in your product, we kindly ask you
    to add your product identification and version in the `User-Agent` HTTP
    header as defined in [RFC7231](https://tools.ietf.org/html/rfc7231#section-5.5.3).

    For a server or standalone application, you could add the following header:

    ```
    User-Agent: your-product-name/1.2.3
    ```

    For a web client integration, please append the product and version in addition
    of the existing browser user agent entry like for example

    ```
    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:82.0) Gecko/20100101 Firefox/82.0 your-product-name/1.2.3
    ```

    This can be achieved in most XHR libraries.

    The user agent information is used to improve our product and
    deliver the best service to you.

    # FAQ
    ## How can I make sure you make real transactions?

    You can always check if the hash for your document was actually
    registered in the Ethereum blockchain using any available Ethereum
    explorer tool like for example [etherscan.io](https://etherscan.io).

    The Ethereum network and smart contract retrieved using the
    [Configuration API](#tag/Configuration)

    Executing
    ```
    curl https://api.testnet.certifaction.io/config
    ```

    will return the information to find the proof of the document
    registration:
    ```
    {
      "network_name":"goerli",
      "smart_contract":"0x39960533db686c4fbca5862316989c31b547363c"
    }
    ```

x-tagGroups:
  - name: API
    tags:
      - Configuration
      - Health
      - Collection
      - File
      - Authentication
      - User
      - Token
      - "Signature Request"
      - Signing Process Management
      - Organization
      - Team Space
      - Settings

security:
  - cookie_id: [ ]
    cookie_hash: [ ]
  - api_token: [ ]
  - jwt_token: [ ]

paths:
  /config:
    get:
      description: Retrieve configuration parameters
      tags:
        - Configuration
      responses:
        "200":
          description: Configuration
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ConfigRepresentation"
      security: [ ]
  /ping:
    get:
      description: A "pong" is returned if the service is running.
      tags:
        - Health
      summary: Ping the server.
      operationId: ping
      responses:
        "200":
          description: API is up and running
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security: [ ]
  /health:
    get:
      description: Returns dependencies health
      tags:
        - Health
      summary: Returns dependencies health
      operationId: health
      responses:
        "200":
          description: All services are good.
          content:
            "*/*":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HealthRepresentation"
        "500":
          description: Internal server error
        "503":
          description: "One or more dependencies are having issues. "
          content:
            "*/*":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HealthRepresentation"
      security: [ ]
  /collection/search:
    get:
      description: Search all user's collections by name. returns paginated result.
      tags:
        - Collection
      parameters:
        - description: Name you want to filter by
          name: name
          in: query
          required: false
          schema:
            type: string
        - description: Type you want to filter by
          name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - certify
              - draft
              - sign
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/by"
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/size"
      operationId: searchCollections
      responses:
        "200":
          description: All collections
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/PaginatedRepresentationCollection"
        "401":
          description: Access denied. Authentication expired or invalid
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  /collection:
    get:
      description:
        Get all user's collections paginated. An optional "name" and/or "status"
        query parameter can be sent to filter the result
      tags:
        - Collection
      parameters:
        - description: Name you want to filter by
          name: name
          in: query
          required: false
          schema:
            type: string
        - description: Status you want to filter by. Can be a single value or a Comma separated list of statuses.
          name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - draft
              - in_progress
              - processed
        - description: Type you want to filter by
          name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - certify
              - draft
              - sign
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/by"
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/size"
      operationId: getCollections
      responses:
        "200":
          description: All collections
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/PaginatedRepresentationCollection"
        "401":
          description: Access denied. Authentication expired or invalid
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    post:
      description: Please note that only the name & strategy (server_salting or
        client_hashing) attribute are recognized.
      tags:
        - Collection
      summary: Create a new collection.
      operationId: createCollection
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionRepresentationMinified"
        required: true
      responses:
        "201":
          description: Created
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CollectionRepresentationMinified"
        "400":
          description: " Validation error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Access denied. Authentication expired or invalid
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    put:
      description: |-
        Please note that only name & downloaded attribute can be changed.
        They're also the only required attributes other than ID
      tags:
        - Collection
      summary: Update a collection.
      operationId: updateCollection
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionRepresentation"
        required: true
      responses:
        "200":
          description: Updated
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CollectionRepresentation"
        "400":
          description: Validation error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/collection/{id}":
    get:
      tags:
        - Collection
      summary: Get collection by id.
      operationId: collectionById
      parameters:
        - description: Collection id you want to retrieve
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: OK
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CollectionRepresentation"
        "400":
          description: Collection id should be a number
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      description:
        Removes a collection if its empty or has only files that are not
        processed (not status in 'processing', 'certified', 'revoked',
        'expired')
      tags:
        - Collection
      summary: Remove a collection.
      operationId: removeCollection
      parameters:
        - description: Collection id you want to remove
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Collection removed
        "400":
          description:
            "Validation error (e.g.: collection contains files in status
            ('registering', 'registered', 'revoked', 'revoking', 'revoked',
            'expired')"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/collection/{id}/download":
    get:
      tags:
        - Collection
      summary: Download collection's files in zip format.
      description:
        File suffix can be added on user level. Please change 'file_suffix'
        through POST /user to generate different suffixes
      operationId: collectionDownload
      parameters:
        - description: Collection id you want to download files from
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: OK, the file is downloaded
          content:
            "*/*":
              schema:
                type: string
                format: binary
        "400":
          description: collection id should be a number
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/collection/{id}/file":
    post:
      summary: Adds a file to a collection.
      description: |
        After a collection has been created add files to it.

        Please note that depending on the collection strategy that was chosen when creating the collection the request body is either of type 'application/json' or 'multipart/form-data'.
        For strategy client_hashing & client_salting use 'application/json' For strategy server_salting use 'multipart/form-data' as files need to be sent. More info in section 'Request Body Schema' below.

      parameters:
        - in: header
          name: Accept-Language
          schema:
            type: string
          description: "Language of the watermark to add. It defaults do English. Supported values are en, fr, it, and de."
          required: false
        - description: Collection id
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - in: query
          name: digital_twin
          schema:
            type: boolean
          description: "When set to 'true' then digital twin feature is enabled. Digital twin flag is only relevant if the collection that the file is added to was created with the 'strategy' = 'server_salting', which will allow for the file to be process on the server side, otherwise the flag is ignored."
      tags:
        - Collection
      requestBody:
        description: >
          Adds a file to a collection. Depending on the strategy you've chosen on your collection, a different content type should be used.
          For strategy client_hashing & client_salting use 'application/json'

          For strategy server_salting use 'multipart/form-data' as files need to be sent.
          For this strategy server adds salt and watermark. If digital twin is enabled, it will also store encrypted file.

          Only server_salting: To handle failure a request per file has to be made, not a list.


          Remember that by adding a file you're not transmitting it to the blockchain.

          For that you'll need to use /collection/{collection_id}/process
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FileRepresentationHashAndName"
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The File to be added
                  type: string
                  format: binary
                priority:
                  description: >
                    The `default` mode aims to strike a balance between transaction cost and the time to get the transaction mined. Its algorithm ensures that the transaction goes through within a reasonable timespan. It automatically reactions to network congestion


                    The `high` priority was built for highly time-sensitive use cases. As it optimizes for speed and competes for a spot in one of the next few blocks of the Ethereum mainnet, higher charges may apply. Please contact us if you’d like to use this option.
                  type: string
                  enum:
                    - default
                    - high
              required:
                - file
      responses:
        "200":
          description: File(s) added
        "400":
          description: >
            Bad request

            This error could be given in different circumstances (the reason is returned as body):
             - The content type you're sending is wrong for the collection's strategy.
             - You're sending more than one file in a collection with server_salting strategy
             - File is empty
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - Collection
      summary: Remove files from a collection.
      description:
        Remove multiple files from a collection (only file which haven't been
        sent to process can be removed).
        security reasons
      operationId: removeFileFromCollection
      parameters:
        - description: Collection id
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: "#/components/requestBodies/FileRepresentationHashArray"
      responses:
        "200":
          description: File removed
        "400":
          description: Validation error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/collection/{id}/file/server_salting":
    post:
      deprecated: true
      description: >
        Deprecated. Please use /collection/{id}/file. Strategy is already defined in the collection

        Adds a file to a collection with strategy 'server_salting'. A new
        request for each file has to be made to handle failure. The request has
        to be made with content type 'multipart/form-data'.


        Remember that by adding a file you're not transmitting it to the blockchain.

        For that you'll need to use /collection/{collection_id}/process
      tags:
        - Collection
      summary: Add a file to a collection with 'server_salting' strategy.
      operationId: addFileToCollectionStrategyServerHashing
      parameters:
        - description: Collection id
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The File to be added
                  type: string
                  format: binary
              required:
                - file
      responses:
        "201":
          description: Created
          content:
            "*/*":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileRepresentation"
        "400":
          description: Validation error. Reason explained in response.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "415":
          description: "Unsupported media type. The file you uploaded could be read-only, be password protected or simply a format we can't read"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description:
            "Unprocessable entity. Are you trying to send files to a collection
            with strategy `client_hashing`? "
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/collection/{id}/file/client_hashing":
    post:
      deprecated: true
      description: >
        Deprecated. Please use /collection/{id}/file. Strategy is already defined in the collection

        Add a file on a client_hashing's collection. The files should be hashed
        using KECCAK-256 and the string sent prefixed with '0x' (hexadecimal).
        Only name and hash fields are needed.


        Remember that by adding a file you're not transmitting it to the blockchain.

        For that you'll need to use /collection/{collection_id}/process
      tags:
        - Collection
      summary: Add a file to a collection with 'client_hashing' strategy.
      operationId: addFileToCollectionStrategyClientHashing
      parameters:
        - description: Collection id
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: "#/components/requestBodies/FileRepresentationArray"
      responses:
        "200":
          description: OK
          content:
            "*/*":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileRepresentation"
        "400":
          description: Validation error. Reason explained in response.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description:
            Unprocessable entity. Are you trying to send hashed files to a
            collection with strategy `server_salting`?
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/collection/{id}/process":
    put:
      tags:
        - Collection
      summary: Register collection's files on the blockchain.
      description:
        The collection's files added to the collection will be registered on the
        blockchain
      operationId: collectionProcess
      parameters:
        - description: Collection id
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - in: query
          name: scope
          schema:
            type: string
            enum:
              - register
              - sign
              - certify
              - retract
          description: "When set overwrites default claim scope"
          required: false
        - in: query
          name: note
          schema:
            type: string
          description: "Set user defined note in the claim (at most 255 characters)"
          required: false
      responses:
        "202":
          description:
            Processing. You can poll /collection/{collection_id} to know the
            status of the collection & files
        "400":
          description: Collection id should be a number
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "402":
          description:
            Payment required. Your current quota doesn't allow to process so
            many documents
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Collection not found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/FileProcessingError"
  #  /fileobject:
  #    post:
  #      tags:
  #        - FileObject
  #      summary: Upload an encrypted file.
  #      description: We take care of storing your encrypted files. A "Bad request" is returned if we detect a known file type.
  #        Files are stored encrypted (again) at rest.
  #      requestBody:
  #        content:
  #          multipart/form-data:
  #            schema:
  #              type: object
  #              properties:
  #                file:
  #                  type: string
  #                  format: binary
  #      responses:
  #        "201":
  #          description: Created
  #          content:
  #            "*/*":
  #              schema:
  #                $ref: "#/components/schemas/FileObjectRepresentationOutput"
  #        "400":
  #          description: >
  #            Bad request. No file sent?
  #        "401":
  #          description: >
  #            Unauthorized.
  #        "409":
  #          description: >
  #            Conflict. Are you uploading a duplicated file?
  #        "500":
  #          description: Internal server error
  #          content:
  #            "*/*":
  #              schema:
  #                $ref: "#/components/schemas/Error"
  #
  #  "/fileobject/{id}":
  #    get:
  #      tags:
  #        - FileObject
  #      summary: Get FileObject by id.
  #      operationId: fileObjectById
  #      parameters:
  #        - description: FileObject id you want to retrieve
  #          name: id
  #          in: path
  #          required: true
  #          schema:
  #            type: integer
  #            format: int64
  #      responses:
  #        "200":
  #          description: Ok
  #          content:
  #            "*/*":
  #              schema:
  #                $ref: "#/components/schemas/FileObjectRepresentationOutput"
  #        "400":
  #          description: >
  #            Bad request. Is the ID numeric?
  #        "404":
  #          description: >
  #            Not found.

  /file:
    get:
      tags:
        - File
      summary: Search files by name.
      description: Searches authenticated user's files by name
      parameters:
        - description: File name
          name: name
          in: query
          required: true
          schema:
            type: string
        - description: Collection Type
          name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - certify
              - draft
              - sign
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/by"
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/size"
      operationId: searchFiles
      responses:
        "200":
          description: Ok
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/PaginatedRepresentationFile"
        "401":
          description: Access denied. Authentication expired
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Creates new file
      description: |
        Creates new file in the system

      tags:
        - File
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FileRepresentationHashAndName"
      responses:
        "200":
          description: File(s) created
        "400":
          description: >
            Bad request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired or invalid
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  /file/register:
    post:
      description: |
        Register a new pdf-file on the blockchain or add another signature to already registered file. Before registering a pdf-file the caller needs to be authenticated.
        You can send a whole file or just the file hash by choosing the appropriate Content-Type.
        The binary of the pdf or file hash and claim encryption key is sent in the request body.\n\n [When using curl to send pdf file pass the file with the '--data-binary' option]
      tags:
        - File
      summary: Register a new pdf-file on the blockchain.
      operationId: registerFile
      parameters:
        - in: header
          name: Accept-Language
          schema:
            type: string
          description: "Language of the watermark to add. It defaults do English. Supported values are en, fr, it, and de."
          required: false
        - in: query
          name: filename
          schema:
            type: string
          description: |
            The name of the file. This should be set to be able to search for or reference the file at a later point.
            The filename parameter is optional.
          required: false
        - in: query
          name: digital_twin
          schema:
            type: boolean
          description: "When set to 'true' then digital twin feature is enabled"
          required: false
        - in: query
          name: scope
          schema:
            type: string
            enum:
              - register
              - sign
              - certify
              - retract
          description: "When set overwrites default claim scope"
          required: false
        - in: query
          name: note
          schema:
            type: string
          description: "Set user defined note in the claim (at most 255 characters)"
          required: false
        - in: query
          name: retrospective
          schema:
            type: boolean
          description: |
            Do only use the 'retrospective' parameter if the files you are registering are already in circulation.
            If this is not the case it is *strongly* recommended to omit the parameter, since
            the 'retrospective'-mode does not guarantee the same level of privacy as a default registration. Moreover,
            some additional features that will be added in the future might not be supported when registering in 'retrospective'-mode.
            Per default (when the 'retrospective' parameter is omitted), the privacy of the file is improved by
            injecting a secret random value into the pdf (salting) before registering the hash of the file on the blockchain.
            The 'retrospective'-mode only hashes the file and registers it on the blockchain.
            The 'retrospective'-mode is activated by setting the query parameter to \"true\" (?retrospective=\"true\").
            The 'retrospective' parameter is optional.
            Learn more: https://app.certifaction.io/support/certification-modes"
          required: false
      requestBody:
        description: The file to be registered.
        content:
          application/pdf:
            schema:
              format: binary
          application/json:
            schema:
              $ref: "#/components/schemas/FileRepresentationHashClaimKey"

      responses:
        "200":
          description: |
            File successfully sent to api and is in the process of being registered on the blockchain.
            The response body will contain the processed pdf which can now be verified.
            Because only the file in the response-body (and not the original file) can be used for verification, the file in the response-body has to be saved.
            The reason only the file in the response-body can be verified is that a secret random value (salt) and watermark has been injected before registering the hash of the file on the blockchain.
            If digital twin feature is enabled, encrypted version document will be stored as well.
            This is not the case in 'retrospective'-mode or when adding another signature to already signed file. In such case, no salt is injected and therefore the original file can be used for verification.
            Learn more: https://app.certifaction.io/support/certification-modes"
          content:
            "application/pdf":
              schema:
                format: binary
        "400":
          description: Validation failed. Details in the response
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error.
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
  "/file/{hash}/verify":
    get:
      tags:
        - File
      parameters:
        - in: path
          required: true
          name: hash
          description:
            The file hash. To get the file hash you want to verify, you must
            hash the binary data in keccak256. Depending on the programming
            language you're using you could do it different ways.
          schema:
            type: string
      summary: Check whether the file has been registered.
      description:
        Checks whether the file has been registered and by whom. A file can be
        revoked, so make sure you handle the returned revoked property.
        If the file isn't
      operationId: verifyFile
      responses:
        "200":
          description: The file hash has been found in the blockchain OR in our database. Please use "on_blockchain" (bool) to check whether has been registered already.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/FileVerificationRepresentation"
        "404":
          description: File not registered
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security: [ ]
  /file/revoke:
    put:
      tags:
        - File
      summary: Schedule files for revocation
      description:
        Revoke multiple files (only your own files and files in status registered can be
        revoked)
      operationId: revokeFile
      requestBody:
        $ref: "#/components/requestBodies/FileRepresentationHashArray"
      responses:
        "200":
          description: File revocation scheduled
        "400":
          description: Validation error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description:
            Access denied. Authentication expired, invalid or you don't have
            rights on this collection
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Filenot found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  /login:
    post:
      tags:
        - Authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRepresentation"
        required: true
      summary: Perform an authentication.
      description:
        Only username and password are taken from the UserRepresentation object
        you send
      operationId: login
      responses:
        "200":
          description: Login successful. Cookies are set and should be handled also on each following request.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/UserRepresentation"
        "403":
          description:
            " Access denied. Either email and or password are wrong or the user
            did not activate his account yet"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security: [ ]
  /logout:
    post:
      tags:
        - Authentication
      summary: Logs the user out.
      operationId: logout
      responses:
        "205":
          description: " Logged out. Refresh environment"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  /user:
    get:
      tags:
        - User
      summary: Retrieve logged in user's info.
      operationId: getUserInfo
      responses:
        "200":
          description: Ok
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/UserRepresentation"
        "401":
          description: Access denied. Authentication expired or invalid
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: " User has been disabled"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    put:
      tags:
        - User
      summary: "Update user's info. "
      description: Only name and file_suffix can be changed for now. id and email are required too
      requestBody:
        $ref: "#/components/requestBodies/UserRepresentation"
      operationId: updateUserInfo
      responses:
        "200":
          description: User information updated
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/UserRepresentation"
        "401":
          description:
            Access denied. Authentication expired, invalid or you're trying to
            update a user you don't have the rights to
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Your user has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    post:
      description: A verification email will be sent to the specified email address.
      tags:
        - User
      summary: Create a new user.
      operationId: createUser
      requestBody:
        $ref: "#/components/requestBodies/UserRepresentation"
      responses:
        "201":
          description: User created. An email has been sent to the user
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/UserRepresentation"
        "400":
          description: Validation failed. Details in the response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description:
            Duplicated entry. A user with the provided email has already been
            registered
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/user/optin/{hash}":
    get:
      description:
        By using the hash in the mail on PUT /user, you'll be able to activate
        that user
      tags:
        - User
      parameters:
        - in: path
          required: true
          name: hash
          description: The hash created on registration, sent via email
          schema:
            type: string
      summary: Verify user by hash.
      operationId: optin
      responses:
        "201":
          description: User verified. A wallet has been created
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/UserRepresentation"
        "409":
          description:
            Duplicated entry. A user with the provided email has already been
            registered
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/user/identity":
    get:
      summary: Get identities for user
      operationId: get-user-identity
      description: Get and filter identities for the currently authenticated user.
      tags:
        - User
      parameters:
        - name: issuer
          description: The identification issuer to filter by
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/IdentityIssuer"
        - name: status
          description: The identification status to filter by. Can be a single value or an array.
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: "#/components/schemas/IdentityStatus"
        - name: signature_jurisdiction
          description: The Signature Jurisdiction to filter by
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/SignatureJurisdiction"
        - name: signature_level
          description: The Signature Level to filter by
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/SignatureLevel"
      responses:
        "200":
          description: Returns list of identities.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/UserRepresentation"
        "400":
          description: Bad request. Might be unknown status, issuer or jurisdiction in filter.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  /token:
    get:
      tags:
        - Token
      summary: List user's tokens
      operationId: token-get-list
      responses:
        "200":
          description: All user's tokens
          content:
            "application/json":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TokenOutput"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

    post:
      tags:
        - Token
      summary: Generate a new token.
      operationId: token-generate
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenInputRepresentation"
      responses:
        "201":
          description: "Token created successfully. This token has to be stored securely by the caller. It is returned only at creation and we don't store them."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/TokenCreatedRepresentation"
        "400":
          description: Validation error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Access denied. Authentication expired or invalid
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/token/{id}":
    delete:
      tags:
        - Token
      summary: Invalidate a token
      operationId: token-invalidate
      parameters:
        - description: Token ID you want to invalidate
          name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Token invalidated
        "400":
          description: Validation error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Access denied. Authentication expired or invalid
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: User has been disabled
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/file/{id}":
    get:
      tags:
        - "File"
      summary: Get file information
      description: Get file information by ID or hash. This endpoint requires you to be either the owner of the file or shared files within the same organization
      parameters:
        - description: File id/hash you want to retrieve information for
          name: id
          in: path
          required: true
          schema:
            type: string

      responses:
        "200":
          description: File by ID or hash found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileRepresentation"
        "403":
          description: "Access forbidden"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
  "/file/{id}/signature/request":
    parameters:
      - name: id
        in: path
        description: The file ID or hash
        required: true
        schema:
          type: string
      - name: team_space_id
        in: query
        description: "The teamspace to assign the resulting signing process to"
        required: false
        schema:
          type: string
    post:
      tags:
        - "Signature Request"
      summary: Create signature request
      description: Create a signature request for a file
      parameters:
        - name: id
          description: File id/hash you want to create a signature request for
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignatureRequestsRepresentation"
      responses:
        "201":
          description: Signature request created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureRequestsRepresentation"
        "400":
          description: "Signatures request for not registered file is forbidden or Missing/Unexpected digital twin URL"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "402":
          description: "Not enough quota to make signature request"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "User not allowed to make signature request for this file"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    get:
      tags:
        - "Signature Request"
      summary: Get signature requests
      description: Get signature requests for a file for the authenticated user
      responses:
        "200":
          description: Signature requests fetched
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SignatureRequestModelRepresentation"
        "400":
          description: "Invalid filehash or other invalid parameter"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
    delete:
      summary: Delete signature requests for file
      tags:
        - Signature Request
      requestBody:
        content:
          application/json:
            schema:
              properties:
                note:
                  type: string
                  maxLength: 255
      responses:
        200:
          description: Deletion successful
        401:
          $ref: "#/components/responses/Unauthorized"
        400:
          description: |
            A validation error occurred. Either:
            1. The `id` parameter is missing;
            2. The request body could not be parsed; or
            3. `body.note` is longer than 255 characters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: |
            You are not allowed to cancel the process because:
            - the signature request was not created by the caller; or
            - the signature request has been completed.
  "/signature/request/{id}/decline":
    parameters:
      - name: id
        in: path
        description: The signature request id
        required: true
        schema:
          type: string
    post:
      tags:
        - "Signature Request"
      summary: Decline signing files
      description: As an invitee user can decline signing files and leave note for the inviter
      requestBody:
        content:
          application/json:
            schema:
              properties:
                note:
                  type: string
                file_ids:
                  type: array
                  items:
                    type: string
              required:
                - note
                - file_ids
      responses:
        "200":
          description: Envelope items declined
        "400":
          description: "Invalid id or other invalid parameter"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
  "/signature/request/{id}/decline/confirm":
    parameters:
      - name: id
        in: path
        description: The signature request id
        required: true
        schema:
          type: string
    post:
      tags:
        - "Signature Request"
      summary: Confirm decline signing files
      description: A requester confirms the declining of signing files and removes invitee from the signatories.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                file_ids:
                  type: array
                  items:
                    type: string
              required:
                - file_ids
      responses:
        "200":
          description: Decline request confirmed.
        "400":
          description: "Invalid id or other invalid parameter"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
  "/signature/request/{id}":
    parameters:
      - name: id
        in: path
        description: The signature request id
        required: true
        schema:
          type: string
    get:
      tags:
        - "Signature Request"
      summary: Get signature request
      description: Get signature request with given id for the authenticated user
      responses:
        "200":
          description: Signature requests fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureRequestModelRepresentation"
        "400":
          description: "Invalid id or other invalid parameter"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]

  "/signature/request/{id}/envelopeitems":
    parameters:
      - name: id
        in: path
        description: The signature request id
        required: true
        schema:
          type: string
    post:
      tags:
        - "Signature Request"
      summary: Add new envelope items
      description: Adds new envelope items to the given signature request if the request has not been modified by the signer.
      requestBody:
        required: true
        description: The list of new envelope items to add.
        content:
          application/json:
            schema:
              properties:
                new_envelope_items:
                  type: array
                  items:
                    type: object
                    properties:
                      file_id:
                        type: string
                      filename:
                        type: string
                      file_url:
                        type: string
                        format: url
                      collection_id:
                        type: integer
                      document_id:
                        type: string
                      signature_position:
                        type: string
                    required:
                      - file_id
                      - filename
                      - document_id
              required:
                - new_envelope_items
      responses:
        "200":
          description: New envelope items were added successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureRequestModelRepresentation"
        "400":
          description: Invalid request body
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: |
            Adding new envelope items was rejected for one of the following reasons:
            1. Every envelope item in the request has been signed;
            2. The client user is not the signature requester;
            3. The client user does not have access to some of the new files in the request; or
            4. The signature request was created with `send_email=true`.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
        - signer_token_deprecated: [ ]

  "/file/{id}/signature/identity":
    parameters:
      - name: id
        in: path
        description: The file ID or hash
        required: true
        schema:
          type: string
    get:
      tags:
        - Signature Request
      summary: Fetch the user's identities used for the given file
      parameters:
        - name: issuer
          in: query
          schema:
            $ref: "#/components/schemas/IdentityIssuer"
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/IdentityStatus"
      responses:
        200:
          description: User identities used with the given file
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/IdentityRepresentation"
        401:
          $ref: "#/components/responses/Unauthorized"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
  "/file/{id}/signature/request/signer/{signerUID}":
    delete:
      tags:
        - "Signature Request"
      summary: Remove signature request
      description: Remove a signature request for a file that was sent to a invited signer
      parameters:
        - name: id
          description: File id/hash
          in: path
          required: true
          schema:
            type: string

        - name: signerUID
          description: Signer's UID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RemoveRequestBody"
      responses:
        "200":
          description: "Signature request removed"
        "403":
          description: "Not allowed to remove signature request"
        "404":
          description: "Signature request not found"
        "500":
          description: " Internal server error"
  "/signature/request":
    post:
      summary: Edit signature request
      tags:
        - Signature Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                id:
                  type: string
                  description: The signature request ID
                name:
                  type: string
                email:
                  type: string
                  description: |
                    The signer's email replacement. Changing the email invalidates the signer token and sends a new one.
                    The signature request will be resent to the new email address.
                signature_position:
                  type: string
                message:
                  type: string
                attachments:
                  type: array
                  items:
                    $ref: "#/components/schemas/SignatureRequestAttachment"
              required:
                - id
      responses:
        200:
          description: Update successful.
        404:
          $ref: "#/components/responses/NotFound"
        409:
          description: The signature request has already been signed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          $ref: "#/components/responses/InternalServerError"
    get:
      summary: Get signature request
      tags:
        - Signature Request
      parameters:
        - $ref: "#/components/parameters/ceritifaction-signer-token"
      responses:
        200:
          description: An array containing only the signature request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureRequestModelRepresentation"
        401:
          $ref: "#/components/responses/Unauthorized"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
  "/file/{id}/signature/request/complete":
    post:
      summary: Send completion email
      tags:
        - Signature Request
      parameters:
        - name: id
          description: File ID or hash
          in: path
          schema:
            type: string
          required: true
      responses:
        200:
          description: Completion email was sent successfully.
        400:
          description: Either the `id` parameter is missing, or some signatures are pending.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
      security:
        - cookie_id: [ ]
          cookie_hash: [ ]
        - api_token: [ ]
        - jwt_token: [ ]
        - signer_token_deprecated: [ ]
  "/address-book/suggest":
    get:
      tags:
        - "Address book"
      summary: Suggests address book entries
      description: Suggests address book entries based on name and email addresses. Data comes from already requested signature requests' sent and, if in an organization, adds organization's users too.
      parameters:
        - description: Name or email you want to get suggestions for
          name: text
          in: query
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Suggestions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AddressBookRepresentation"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/organization":
    post:
      tags:
        - "Organization"
      summary: Create organization
      requestBody:
        $ref: "#/components/requestBodies/OrganizationRepresentation"

      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: "#/components/schemas/OrganizationRepresentation"
        "403":
          description: "Forbidden"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict. A user can belong to a maximum of one organization (and create only one)"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  "/organization/{id}":
    get:
      tags:
        - Organization
      summary: Get organization by id
      operationId: organizationById
      parameters:
        - description: Organization id you want to retrieve
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/OrganizationRepresentation"
        "403":
          description: Access forbidden
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: " Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/organization/{id}/user":
    post:
      tags:
        - "Organization"
      summary: Invite user
      description: "A user could be invited multiple times, assuming he didn't accept the invite yet. An email is sent out for each invitation"
      parameters:
        - description: Organization id you want to invite the user to
          name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/OrganizationUserInvite"

      responses:
        "200":
          description: Invited
        "403":
          description: "Forbidden"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict. A user might have already been joined"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/organization/{id}/role":
    post:
      tags:
        - "Organization"
      summary: Change user's role
      description: "Change/reassign a user's role. This can be used before the user accepts the invitation too. Only users with an admin role can execute this action. We don't allow changing the last remaining admin to a non-admin role."
      parameters:
        - description: Organization id the user is in
          name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/OrganizationRoleAssign"

      responses:
        "200":
          description: Role changed successfully
        "403":
          description: "Forbidden. Only users with an administrator role can change users' roles"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict. Are you changing the last remaining administrator to a normal role?"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/organization/role/{id}":
    put:
      parameters:
        - description: Role ID
          name: id
          in: path
          required: true
          schema:
            type: string
      tags:
        - "Organization"
      summary: Update an existing role
      requestBody:
        $ref: "#/components/requestBodies/OrganizationRoleCreateOrUpdate"

      responses:
        "200":
          description: Role changed successfully
        "403":
          description: "Forbidden. Only users with an administrator type role can change roles"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Role not found"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict. A role with the same name exists already"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - "Organization"
      summary: Delete a role

      responses:
        "200":
          description: Role deleted successfully
        "403":
          description: "Forbidden. Only users with an administrator type role can delete roles"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/organization/role":
    post:
      tags:
        - "Organization"
      summary: Create a role
      requestBody:
        $ref: "#/components/requestBodies/OrganizationRoleCreateOrUpdate"

      responses:
        "200":
          description: Role created successfully
        "403":
          description: "Forbidden. Only users with an administrator type role can create roles"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Role not found"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict. A role with the same name exists already"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
  /team-space/organization/:id:
    get:
      tags:
        - "Team Space"
      summary: List organization team spaces (only for org admins)
      parameters:
        - description: Organization id the user is admin of
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Team spaces listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TeamSpace"
        "401":
          description: "Unauthorized"
        "500":
          description: "Internal server error"
  /team-space:
    post:
      tags:
        - "Team Space"
      summary: Create a team space
      requestBody:
        $ref: "#/components/requestBodies/TeamSpaceCreate"
      responses:
        "201":
          description: Team space created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamSpace"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          description: "Internal server error"
    get:
      tags:
        - "Team Space"
      summary: List user team spaces
      responses:
        "200":
          description: Team spaces listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TeamSpace"
        "400":
          description: "Bad request"
        "500":
          description: "Internal server error"

  /team-space/{id}:
    get:
      tags:
        - "Team Space"
      summary: Get a team space
      parameters:
        - description: Team space id
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successfully got teams pace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamSpace"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"

    delete:
      tags:
        - "Team Space"
      summary: Archive a team space
      parameters:
        - description: Team space id
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: "No Content"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"

  /team-space/{id}/rename:
    patch:
      tags:
        - "Team Space"
      summary: Rename a team space
      parameters:
        - description: Team space id
          name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/TeamSpaceRename"
      responses:
        "204":
          description: "No Content"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"

  /team-space/{id}/restore:
    put:
      tags:
        - "Team Space"
      summary: Restore an archived team space
      parameters:
        - description: Team space id
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: "No content"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"
  /team-space/{id}/members:
    parameters:
      - description: Team space id
        name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - "Team Space"
      summary: List team space members
      responses:
        "200":
          description: Team space members listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TeamSpaceMember"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"
  /team-space/{id}/members/v2:
    parameters:
      - description: Team space id
        name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - "Team Space"
      summary: List team space members v2
      responses:
        "200":
          $ref: "#/components/schemas/TeamSpaceMembersV2"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"
    post:
      tags:
        - "Team Space"
      summary: Add a member to a team space
      requestBody:
        $ref: "#/components/requestBodies/TeamSpaceAddMembers"
      responses:
        "201":
          $ref: "#/components/schemas/TeamSpaceMember"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"

  /team-space/{id}/members/{memberId}:
    parameters:
      - description: Team space id
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Team space member id
        name: memberId
        in: path
        required: true
        schema:
          type: string
    delete:
      tags:
        - "Team Space"
      summary: Remove a member from a team space
      responses:
        "204":
          description: "No content"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"

  /team-space/{id}/signing-processes:
    post:
      tags:
        - "Team Space"
      summary: Add a signing process to a team space
      requestBody:
        $ref: "#/components/requestBodies/TeamSpaceAddSigningProcess"
      responses:
        "201":
          description: "Created"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"

  /team-space/{id}/tags:
    post:
      tags:
        - "Team Space"
      summary: Add a tag to a team space
      requestBody:
        $ref: "#/components/requestBodies/TeamSpaceAddTag"
      responses:
        "201":
          description: "Created"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "500":
          $ref: "#/components/schemas/Error"

  /signing-processes:
    get:
      operationId: list-signing-processes
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/size"
        - name: participation
          description: Limit results to signing processes where the user was either the initiator or an invitee.
          in: query
          schema:
            type: string
            enum:
              - initiator
              - invitee
        - name: "team_space_id"
          description: "Filter the signing processes by team space ID. Use 'all' to get processes from all spaces."
          in: query
          schema:
            type: string
        - name: tags
          description: Filter the signing processes by tag ID list
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
      summary: List user's signing processes
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SigningProcessList"
          description: List of user's signing processes
        401:
          $ref: "#/components/responses/Unauthorized"
        500:
          $ref: "#/components/responses/InternalServerError"
      tags:
        - Signing Process Management

  /signing-processes/{signing_process_id}:
    get:
      operationId: get-signing-process
      parameters:
        - name: signing_process_id
          in: path
          schema:
            type: string
          required: true
      summary: Get a signing process by ID
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SigningProcess"
          description: The signing process
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        500:
          $ref: "#/components/responses/InternalServerError"
      tags:
        - Signing Process Management

  /signing-processes/{signing_process_id}/tags:
    put:
      operationId: update-signing-process-tags
      summary: Set signing process tags
      description: |
        This API replaces the tags on the given signing process with the given tags (`$request.body#tag_ids`).

        You can implement moving a signing process from `folderA` to `folderB` using this API
        by sending `$request.body#tag_ids` with `folderB`'s ID included and `folderA`'s ID excluded.
      parameters:
        - name: signing_process_id
          in: path
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                tag_ids:
                  description: IDs of tags to set.
                  type: array
                  items:
                    type: string
              required:
                - tag_ids
      responses:
        204:
          description: The signing processes was successfully tagged.
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        422:
          $ref: "#/components/responses/UnprocessibleEntity"
        500:
          $ref: "#/components/responses/InternalServerError"
      tags:
        - Signing Process Management

  /signing-processes/send-invitation:
    post:
      operationId: send-invitation
      summary: Send invitation for a signature request
      description: |
        This would let you send an invitation for a signature request.
        Note that an invitation is already sent on signature request's creation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                signature_request_id:
                  description: Signature request's ID
                  type: string
                message:
                  description: Optional reminder message to the signer.
                  type: string
                  maxLength: 1000
              required:
                - signature_request_id
      responses:
        200:
          description: Invitation sent.
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
          description: "You might be trying to resend an invite for a signature request that hasn't reached its `sign_order`. "
        500:
          $ref: "#/components/responses/InternalServerError"
      tags:
        - Signing Process Management

  "/tags":
    get:
      operationId: list-tags
      summary: List user's tags
      tags:
        - Signing Process Management
      responses:
        200:
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Tag"
          description: List of tags created by the user
    post:
      summary: Create a new tag
      tags:
        - Signing Process Management
      description: |
        Creates a new tag with the given name for the request user.
        Tag names are unique per user: any existing tag with the same name will be
        returned rather than duplicated. Thus, this API operation is idempotent.
      operationId: create-tag
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
              required:
                - name
        required: true
      responses:
        201:
          description: Tag created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tag"

  "/tags/{tag_id}":
    parameters:
      - name: tag_id
        in: path
        schema:
          type: string
        required: true
    delete:
      operationId: delete-tag
      summary: Delete a tag
      tags:
        - Signing Process Management
      responses:
        204:
          description: Tag was succesfully deleted.
        500:
          $ref: "#/components/responses/InternalServerError"
    patch:
      operationId: rename-tag
      summary: Rename a tag
      tags:
        - Signing Process Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                  description: The new tag name
              required:
                - name
      responses:
        200:
          description: Tag was succesfully renamed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tag"
        500:
          $ref: "#/components/responses/InternalServerError"

  "/setting":
    get:
      tags:
        - "Settings"
      summary: List user's settings
      description: Settings are inherited from organization's roles and can only be changed by the organization's administrator.

      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SettingRepresentation"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
    post:
      tags:
        - "Settings"
      summary: Update settings
      description: Update user role's settings.
      requestBody:
        $ref: "#/components/requestBodies/SettingUpdateArray"

      responses:
        "200":
          description: Ok
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden. You're not allowed to change settings for the entity ID given"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  "/setting/{entity_id}":
    get:
      tags:
        - "Settings"
      summary: Get settings by entity id
      description: The administrator of an organization can retrieve settings by entity id
      parameters:
        - description: Entity ID you want to get settings for
          name: entity_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SettingRepresentation"
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Access denied"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

    post:
      tags:
        - "Settings"
      summary: Update settings by entity ID
      description: Update organization role's settings by entity ID. Only the organization's administrator can change it
      parameters:
        - description: Entity ID you want to get settings for
          name: entity_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/SettingUpdateArray"

      responses:
        "200":
          description: Ok
        "401":
          description: "Unauthorized"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden. You're not allowed to change settings for the entity ID given"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  /setting/upload:
    post:
      tags:
        - "Settings"
      summary: Upload files for settings.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                key:
                  type: string
      responses:
        "201":
          description: Created
          content:
            "*/*":
              schema:
                properties:
                  url:
                    type: string

  /request-otp:
    post:
      tags:
        - "OTP"
      summary: Request OTP for a phone number
      description: Request OTP for a phone number
      requestBody:
        content:
          application/json:
            schema:
              properties:
                phone:
                  type: string
                  description: The phone number of the user
              required:
                - phone
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OtpRequestResponse"
        "400":
          description: "Bad request"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

  /confirm-otp:
    post:
      tags:
        - "OTP"
      summary: Confirms OTP for a reference
      description: Confirm OTP for a reference
      requestBody:
        content:
          application/json:
            schema:
              properties:
                reference:
                  type: string
                  description: The reference that was returned when the otp was created
                otp:
                  type: string
                  description: The otp that was sent to the user
              required:
                - reference
                - otp
      responses:
        "200":
          description: Ok
        "400":
          description: "Bad request"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal server error"
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/Error"

components:
  parameters:
    page:
      description: Page you want to retrieve, starting from 1
      name: page
      in: query
      required: false
      schema:
        type: integer
        format: int64
    by:
      description:
        Sort by a field. To use in conjunction with 'sort'. Only name, status,
        filename & total_count can be sorted
      name: by
      in: query
      required: false
      schema:
        type: string
    sort:
      description: Sort (desc/asc). To use in conjunction with 'by'
      name: sort
      in: query
      required: false
      schema:
        type: string
    size:
      description: Elements per page you want to show. Default 10
      name: size
      in: query
      required: false
      schema:
        type: integer
        format: int64
    ceritifaction-signer-token:
      name: Certifaction-Signer-Token
      description: The signer token for the signature request.
      in: header
      schema:
        type: string
      required: true
  requestBodies:
    FileRepresentationArray:
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/FileRepresentation"
      required: true
    FileRepresentationHashArray:
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/FileRepresentationHashAndName"
      required: true
    UserRepresentation:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UserRepresentation"
      required: true
    OrganizationRepresentation:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrganizationRepresentation"
      required: true
    OrganizationUserInvite:
      content:
        application/json:
          schema:
            properties:
              email:
                type: string
              role_id:
                type: string
      required: true
    OrganizationRoleAssign:
      content:
        application/json:
          schema:
            properties:
              user_uid:
                type: string
                description: "Either user_uid OR invite_email have to be set, depending if the user already joined or not"
              invite_email:
                type: string
              role_id:
                type: string
    OrganizationRoleCreateOrUpdate:
      content:
        application/json:
          schema:
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 100
              admin:
                type: boolean
            required:
              - name
              - admin
    SettingUpdateArray:
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                value:
                  type: string
                default_value:
                  type: string
    TeamSpaceRename:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
            required:
              - name
    TeamSpaceAddTag:
      content:
        application/json:
          schema:
            type: object
            properties:
              tag_id:
                type: string
            required:
              - name

    TeamSpaceAddSigningProcess:
      content:
        application/json:
          schema:
            type: object
            properties:
              signing_process_id:
                type: string
            required:
              - signing_process_id

    TeamSpaceCreate:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
              member_user_ids:
                type: array
                items:
                  type: string
              member_user_emails:
                type: array
                items:
                  type: string
            required:
              - name
    TeamSpaceAddMembers:
      content:
        application/json:
          schema:
            type: object
            properties:
              member_user_ids:
                type: array
                items:
                  type: string
              member_user_emails:
                type: array
                items:
                  type: string
  securitySchemes:
    api_token:
      name: Authorization
      in: header
      type: apiKey
    signer_token_deprecated:
      type: http
      scheme: bearer
      bearerFormat: Bearer <token>
    jwt_token:
      type: http
      scheme: bearer
      bearerFormat: Bearer <token>
      description: User's JWT token (currently obtained from Auth0).
    cookie_id:
      name: id
      description: The user's id for cookie authentication. Must be used with `cookie_hash`.
      in: cookie
      type: apiKey
    cookie_hash:
      name: hash
      description: The user's hash for cookie authentication. Must be used with `cookie_id`.
      in: cookie
      type: apiKey
  responses:
    Conflict:
      description: The operation requested to modify an outdated resource.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: The request's authentication does not give access right to complete the operation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalServerError:
      description: The server is having a bad day.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: The request lacks sufficient authentication to proceed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnprocessibleEntity:
      description: The request is understood but cannot be processed, likely due to a constraint violation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    IdentityIssuer:
      type: string
      enum:
        - idnow
        - nect
        - intrum
        - swisscom
    IdentityStatus:
      type: string
      enum:
        - unverified
        - pending
        - manual-check
        - submitted
        - completed
        - confirming
        - ready-to-sign
        - verified
        - failed
    SignatureJurisdiction:
      type: string
      enum:
        - eIDAS
        - ZertES
    IdentityRepresentation:
      properties:
        uid:
          type: string
        user_uid:
          type: string
        issuer:
          $ref: "#/components/schemas/IdentityIssuer"
        status:
          $ref: "#/components/schemas/IdentityStatus"
        failure_reason:
          type: string
        allow_manual_check:
          type: boolean
        verification_url:
          type: string
        verification_id:
          type: string
        evidence_url:
          type: string
        proof:
          type: string
        # Fields derived from https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
        email:
          type: string
        phone_number:
          type: string
        name:
          type: string
        title:
          type: string
        suffix:
          type: string
        given_name:
          type: string
        middle_name:
          type: string
        family_name:
          type: string
        street_address:
          type: string
        locality:
          type: string
        region:
          type: string
        postal_code:
          type: string
        country:
          type: string
        gender:
          type: string

        # Additional fields returned by IDNow
        birthplace:
          type: string
        birthday:
          type: string
        citizenship:
          type: string
        language:
          type: string

        signature_level:
          type: string
        signature_jurisdiction:
          type: string
        # Additional fields returned by HIN and SWITCH
        affiliation:
          type: string
        identification_method:
          type: string
      required:
        - uid
        - user_uid
        - issuer
        - status
    UserRepresentation:
      properties:
        external_id:
          type: string
        title:
          type: string
        postal_code:
          type: string
        location:
          type: string
        encrypt_claims:
          type: boolean
        verified_by:
          type: string
        address:
          type: string
        disabled:
          type: boolean
        email:
          type: string
        eth_address:
          type: string
        id:
          type: integer
          format: int64
        name:
          type: string
        first_name:
          type: string
        middle_names:
          type: string
        last_name:
          type: string
        citizenship:
          type: string
          description: "User citizenship in ISO 3166 alpha-2 standard"
        mobile_number:
          type: string
          description: "Mobile number (if any) in E.164 standard"
        affiliation:
          type: string
        old_password:
          type: string
        password:
          type: string
          description:
            "Clear text password, only used on user creation! Only used as
            input. "
        password_repeat:
          type: string
          description: Only used on user creation
        quota:
          type: integer
          format: int64
          description: "The number of remaining file registration credits if the `subscription_type` is equal to `credits`"
        subscription_type:
          type: string
          description: "The type of subscription, either `credits` or `flat_rate`"
        file_suffix:
          type: string
          description:
            "A user can choose a file suffix to have when downloading the
            batch's zip file. For ex: '_secured' will have all files in the zip
            called 'A_Random_name_secured.pdf'"
        idnow_verified:
          type: boolean
          description: Whether the user has been verified by IDNow
        organizations:
          type: array
          items:
            $ref: "#/components/schemas/OrganizationRepresentation"
          description: The organizations the user belongs to (if any).
    CollectionRepresentation:
      properties:
        downloaded:
          type: boolean
        files:
          type: array
          items:
            $ref: "#/components/schemas/FileRepresentation"
        id:
          type: integer
          format: int64
          description: the id for this collection
        name:
          type: string
          description: collection's name
        ready_count:
          type: integer
          format: int64
          description: Quantity of files ready to be registered
        registered_count:
          type: integer
          format: int64
          description:
            Quantity of files which have been registered already to the
            blockchain
        registering_count:
          type: integer
          format: int64
          description: Quantity of files that this collection has (all statuses)
        registration_failed_count:
          type: integer
          format: int64
          description: Quantity of files which have failed
        status:
          description:
            "draft: there are still files to be uploaded, in_progress: there are
            files which are being registered and didn't complete yet, while
            processed means that all files in this collection have been
            registered"
          type: string
          enum:
            - draft
            - in_progress
            - processed
        strategy:
          description:
            server_salting will hash the files on server side. These files will
            have to be downloaded again. More secure option. client_hashing
            requires that you hash the files' binary data in keccak256
          type: string
          enum:
            - client_hashing
            - server_salting
        total_count:
          type: integer
          format: int64
        upload_failed_count:
          type: integer
          format: int64
    CollectionRepresentationMinified:
      properties:
        downloaded:
          type: boolean
        id:
          type: integer
          format: int64
          description: the id for this collection
        name:
          type: string
          description: collection's name
        ready_count:
          type: integer
          format: int64
          description: Quantity of files ready to be registered
        registered_count:
          type: integer
          format: int64
          description:
            Quantity of files which have been registered already to the
            blockchain
        registering_count:
          type: integer
          format: int64
          description: Quantity of files that this collection has (all statuses)
        registration_failed_count:
          type: integer
          format: int64
          description: Quantity of files which have failed
        status:
          description:
            "draft: there are still files to be uploaded, in_progress: there are
            files which are being registered and didn't complete yet, while
            processed means that all files in this collection have been
            registered"
          type: string
          enum:
            - draft
            - in_progress
            - processed
        strategy:
          description:
            server_salting will hash the files on server side. These files will
            have to be downloaded again. More secure option. client_hashing
            requires that you hash the files' binary data in keccak256
          type: string
          enum:
            - client_hashing
            - server_salting
        total_count:
          type: integer
          format: int64
        upload_failed_count:
          type: integer
          format: int64
    TeamSpaceMembersV2:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: "#/components/schemas/TeamSpaceMember"
        invites:
          type: array
          items:
            $ref: "#/components/schemas/TeamSpaceInvite"
    TeamSpaceInvite:
      type: object
      properties:
        id:
          type: string
        invite_email:
          type: string
    FileRepresentation:
      properties:
        collection_id:
          type: integer
          format: int64
        collection_name:
          type: string
        created_at:
          type: string
          format: date-time
        hash:
          type: string
        name:
          type: string
        registered_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - ready
            - registering
            - revoking
            - revoked
            - revocation_failed
            - expired
            - registered
            - preparation_failed
            - unknown
        txHash:
          type: string
        signature_requests:
          type: array
          items:
            $ref: "#/components/schemas/SignatureRequestRepresentation"
        digital_twin:
          description: "A digital twin file can't be removed completely from a digital archive. If you want to delete files completely you have to pass this as `false`. An empty value is treated as unknown and won't be deleted."
          type: boolean
          required: false
    SignatureRequestRepresentation:
      properties:
        uid:
          type: string
          description: Signer's UID
        name:
          type: string
        email:
          type: string
        file_hash:
          type: string
        legal_weight:
          type: string
        signed:
          type: boolean
          description: "Whether all envelope items have been signed. To know for each item, refer to envelope item's status"
        cancelled:
          type: boolean
          description: Whether the signature request have been cancelled or not
        jurisdiction:
          type: string
          description: Optional jurisdiction. For example 'eIDAS' or 'ZertES'
    SignatureRequestAttachment:
      properties:
        filename:
          type: string
        url:
          type: string
      required:
        - filename
        - url
    FileRepresentationCondensed:
      properties:
        hash:
          type: string
        registered_at:
          type: string
          format: date-time
        txHash:
          type: string
    FileRepresentationHashAndName:
      properties:
        hash:
          type: string
        name:
          type: string
    FileRepresentationHashClaimKey:
      properties:
        hash:
          type: string
        claim_key:
          type: string
          description: The public key (in hex format, ECDSA) to encrypt claims with.
    LoginRepresentation:
      properties:
        email:
          type: string
        password:
          type: string
          description: Clear text password
    FileVerificationRepresentation:
      properties:
        issuer_name:
          type: string
          description:
            The owner name, verified and coming from the blockchain. Do not
            confuse with 'user_name'
        issuer_img:
          type: string
          description: unused for now
        issuer_address:
          type: string
          description: Owner's Ethereum address. Ex.
            0x84af69b785f244dc65b2d34ced19c76ec2d519ac
        issuer_verified:
          type: boolean
        user_name:
          type: string
          description:
            This property is set whenever the owner is also registered on
            certifaction. If empty, the user isn't registered on certifaction
            and the file has been registered directly on the smart contract.
            If `on_blockchain` is true, use `issuer_name`. If it's not, use `user_name` as things aren't finalized yet, therefore IssuerName will be empty.
        registration_date:
          type: string
          format: date-time
        on_blockchain:
          type: boolean
        file:
          $ref: "#/components/schemas/FileRepresentationCondensed"
        revoked:
          type: boolean
          description:
            File can be revoked. If this value is true, then the file has been
            revoked by the owner!
    OrganizationRepresentation:
      properties:
        id:
          type: string
        name:
          type: string
        name_verified:
          type: boolean
        base_url:
          type: string
          description: "Used by customers to set their own company's URL. That URL is used when sending emails"
        quota:
          type: integer
          nullable: true
        roles:
          type: array
          items:
            $ref: "#/components/schemas/OrganizationRoleRepresentation"
          description: Organization's available roles.
        organization_users:
          type: array
          items:
            $ref: "#/components/schemas/OrganizationUserRepresentation"
    SettingRepresentation:
      properties:
        id:
          type: string
        value:
          type: string
        default_value:
          type: string

    "Limit-Offset-Page-Properties":
      properties:
        total_elements:
          type: integer
          format: int64
          minimum: 0
          description: Total elements overall
        total_pages:
          type: integer
          format: int64
          minimum: 0
          description: Total pages you can navigate using the ?page query parameter
        current_page:
          type: integer
          format: int64
          minimum: 1
          description: The page you're currently in.

    PaginatedRepresentationCollection:
      allOf:
        - $ref: "#/components/schemas/Limit-Offset-Page-Properties"
        - type: object
          properties:
            content:
              type: array
              nullable: true
              description: The requested collection pages.
              items:
                $ref: "#/components/schemas/CollectionRepresentationMinified"

    PaginatedRepresentationFile:
      allOf:
        - $ref: "#/components/schemas/Limit-Offset-Page-Properties"
        - type: object
          properties:
            content:
              type: array
              nullable: true
              description: The requested file list.
              items:
                $ref: "#/components/schemas/FileRepresentation"

    ConfigRepresentation:
      properties:
        network_name:
          type: string
          enum:
            - goerli
            - mainnet
        smart_contract:
          type: string
          description: Smart contract's Ethereum address
    HealthRepresentation:
      properties:
        service_name:
          type: string
          enum:
            - database
            - ethereum
        status:
          type: string
          enum:
            - UP
            - DOWN
        description:
          type: string
          description: A simple description. Could help to locate the issue

    Error:
      properties:
        message:
          type: string
        validation_errors:
          type: array
          description: "Only on validation failure (error 400) this property will be shown."
          items:
            $ref: "#/components/schemas/ValidationError"

    ValidationError:
      type: object
      properties:
        field:
          type: string
          x-go-name: Field
        reason:
          type: string
          x-go-name: Reason
      x-go-package: github.com/certifaction/apimodel

    FileProcessingError:
      properties:
        message:
          type: string
        files:
          type: array
          description: "On internal errors where some files might have been processed and others failed an array of files containing the file-hash and file-status will be returned."
          items:
            $ref: "#/components/schemas/FileProcessingResponse"

    FileProcessingResponse:
      type: object
      properties:
        hash:
          type: string
          x-go-name: Hash
        status:
          type: string
          x-go-name: Status

    TokenInputRepresentation:
      properties:
        name:
          type: string
          description: A name/note of the token to make it recognizable. Min 3, max. 60 characters
        organization:
          type: boolean
          description: Whether should be an organization token or assigned to the current user. Only users having admin rights within the organization can select this option
        valid_until:
          type: string
          format: date-time
          description: An optional date in the future the token is set to expire. If not set, the token is not set to expire.

    TokenCreatedRepresentation:
      properties:
        raw_value:
          type: string
          description: The API token. Caller has to store this securely. Use this to make your machine-to-machine calls, passing it as 'Authorization' header

    TokenOutput:
      properties:
        id:
          type: integer
          description: Identifier
        name:
          type: string
          description: The token's name (or note) the user gave to recognize it more easily
        created_at:
          type: string
          format: date
        valid_until:
          type: string
          format: date-time
          description: An optional date in the future the token is set to expire. If not set, the token is not set to expire.
        role_id:
            type: string
            description: If you're creating an organization token, the role the token is assigned to. If not set, the token gets the default system "user" role.

    SignatureRequestsRepresentation:
      description: Parameters for creating the signature request.
      properties:
        encryption_params:
          type: object
          properties:
            encryption_key:
              type: string
              description: The key used to encrypt each document encryption key.
            password_algorithm:
              type: string
              description: The encryption key password algorithm, for Privacy 2.0. We redact this also to lose access.
              enum:
                - xor-b58
          required:
            - key
          description: Omit this if `send_email` is false. We store this information temporarily to facilitate signing.
        send_email:
          type: boolean
          description: If set to true, requires Digital-Twin-Link to be set and don't return SigningTokens
        signing_process_name:
          type: string
          minLength: 1
          maxLength: 80
        signers:
          type: array
          items:
            $ref: "#/components/schemas/__SignatureRequestRepWithEnvelopeItems"
          description: A list of signers
      required:
        - signers
        - signing_process_name

    SignatureLevel:
      type: string
      enum:
        - QES
        - AES
        - PES
        - standard

    Jurisdiction:
      type: string
      enum:
        - eIDAS
        - ZertES
        - ""

    Locale:
      type: string
      enum:
        - de
        - en
        - fr
        - it
      description: Available locale options. In signature requests, it specifies the language translation for the signing request email.

    EnvelopeItem:
      type: object
      properties:
        collection_id:
          type: integer
        document_id:
          type: string
        filename:
          type: string
        file_id:
          type: string
        legal_weight:
          $ref: "#/components/schemas/SignatureLevel"
        jurisdiction:
          $ref: "#/components/schemas/Jurisdiction"
        link:
          type: string
          description: Digital-Twin-Link. Only used for Email.
        signature_position:
          type: string
          description: An opaque JSON value containing the position representation used by the client.
        status:
          enum:
            - unsigned
            - signed
      required:
        - file_id
        - legal_weight

    __SignatureRequestRepDeprecatedFields:
      type: object
      properties:
        signature_position:
          type: string
          deprecated: true
          description: An opaque JSON value containing the position representation used by the client.

    __SignatureRequestRepCommonFields:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        language:
          $ref: "#/components/schemas/Locale"
        message:
          type: string
          description: Initiator's message to the signer.
          maxLength: 100000
        sign_order:
          type: integer
          description: A number indicating the order you want the document to be signed. Multiple signature requests of the same number are accepted.
        signer_token:
          type: string
          description: Signer token return when `send_email=false` when creating the signature request.
        transaction_id:
          type: string
        webhook_url:
          type: string
          description: "I don't know what this does yet. I guess it helps with integration. TODO: find out."

    __SignatureRequestRepDeprecated:
      type: object
      deprecated: true
      allOf:
        - $ref: "#/components/schemas/__SignatureRequestRepCommonFields"
        - $ref: "#/components/schemas/__SignatureRequestRepDeprecatedFields"

    __SignatureRequestRepWithEnvelopeItems:
      type: object
      allOf:
        - $ref: "#/components/schemas/__SignatureRequestRepCommonFields"
        - properties:
            envelope_items:
              type: array
              items:
                $ref: "#/components/schemas/EnvelopeItem"
            has_encrypted_file_keys:
              type: boolean
          required:
            - envelope_items

    SignatureRequestRep:
      type: object
      oneOf:
        - $ref: "#/components/schemas/__SignatureRequestRepDeprecated"
        - $ref: "#/components/schemas/__SignatureRequestRepWithEnvelopeItems"

    SignatureRequestModelRepresentation:
      properties:
        id:
          type: string
        signing_process_id:
          type: string
        envelope_items:
          type: array
          items:
            $ref: "#/components/schemas/EnvelopeItem"
        file_hash:
          type: string
        filename:
          type: string
        has_encrypted_file_keys:
          type: boolean
        legal_weight:
          type: string
        jurisdiction:
          type: string
        used_identification_at:
          type: string
        signed:
          type: boolean
        signed_at:
          type: string
          format: date-time
        requester:
          $ref: "#/components/schemas/SignatureRequestModelUserRepresentation"
        signer:
          $ref: "#/components/schemas/SignatureRequestModelUserRepresentation"
        cancelled:
          type: boolean
        cancellation_note:
          type: string
        sign_order:
          type: integer
        signature_position:
          type: string
        theme:
          properties:
            name:
              type: string
          required:
            - name
        consent_url:
          type: string
      required:
        - id
        - envelope_items
        - legal_weight
        - jurisdiction
        - signed
        - requester
        - signer
        - cancelled
    SignatureRequestModelUserRepresentation:
      properties:
        name:
          type: string
        name_verified:
          type: boolean
        email:
          type: string
        email_verified:
          type: boolean
    RemoveRequestBody:
      properties:
        note:
          type: string
          description: A note containing a small text explaining why the signature request was removed. The note will be sent in the cancel-email to the signer.
    AddressBookRepresentation:
      properties:
        name:
          type: string
        email:
          type: string
    OrganizationUserRepresentation:
      properties:
        is_admin:
          type: boolean
          description: "True if the user has an admin role assigned to him within this organization."
        roles:
          type: array
          items:
            $ref: "#/components/schemas/OrganizationRoleRepresentation"
        user:
          $ref: "#/components/schemas/UserRepresentation"
        status:
          enum:
            - joined
            - invited
            - rejected
        role:
          type: string
          description: "Please refer to `roles` or `is_admin`."
          deprecated: true
        teamspaces:
          type: array
          description: |
            Team Spaces that the user belongs to.

            This field may be deprecated in a future refactoring. We added it to get Team Space labels on the user management view quickly.
          items:
            properties:
              id:
                type: string
                description: Team Space ID
              name:
                type: string
                description: Team Space name
            required:
              - id
              - name

    OrganizationRoleRepresentation:
      properties:
        id:
          type: string
        name:
          type: string
          description: "Role name. A name could be for example 'User' or 'Admin'"
        default:
          type: boolean
          description: "Indicates if the role is used as default role when adding new users or create tokens for the organization"
        admin:
          type: boolean
          description: "Whether the role has admin rights or not"

    SigningProcess:
      properties:
        created_at:
          type: string
          readOnly: true
        name:
          type: string
        owner_uid:
          type: string
          readOnly: true
        process_id:
          type: string
          readOnly: true
        tag_ids:
          type: array
          items:
            type: string
        signature_requests:
          type: array
          items:
            $ref: "#/components/schemas/SignatureRequestModelRepresentation"
        status:
          type: string
          enum:
            - completed
            - pending
            - cancelled
      required:
        - created_at
        - name
        - owner_uid
        - process_id
        - signature_requests

    SigningProcessList:
      allOf:
        - $ref: "#/components/schemas/Limit-Offset-Page-Properties"
        - type: object
          properties:
            content:
              type: array
              nullable: true
              description: The requested signing process list.
              items:
                $ref: "#/components/schemas/SigningProcess"

    Tag:
      properties:
        created_at:
          type: string
          readOnly: true
        id:
          type: string
          readOnly: true
        name:
          type: string
        owner_uid:
          type: string
          readOnly: true
      required:
        - created_at
        - id
        - name
        - owner_uid

    TeamSpace:
      properties:
        id:
          type: string
        name:
          type: string
        organization_id:
          type: string
        creator_uid:
          type: string
        archived:
          type: boolean
        can_archive:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    TeamSpaceMember:
      properties:
        id:
          type: string
        team_space_id:
          type: string
        user_uid:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    OtpRequestResponse:
      properties:
        reference:
          type: string