swagger.yaml

swagger: '2.0'
info:
  description: |
    This document describes passbolt backend REST APIs. They work over HTTPS so they are language/framework agnostic. Clients can consume them in their language of choice using the HTTPS protocol.
  version: "2.8.3"
  title: "passbolt API Reference"
  termsOfService: "https://www.passbolt.com/terms"
  contact:
    email: contact@passbolt.com
  license:
    name: AGPL-3.0
    url: 'http://www.gnu.org/licenses/agpl-3.0.html'
host: www.passbolt.com
basePath: /
tags:
  - name: Auth
    description: Authentication endpoints
  - name: Resource
    description: |
      In passbolt, passwords are split into two different entities: Resources and Secrets. Passwords metadata are internally known as `Resources` and are represented as one object containing the name, username, the URL amongst other fields. While the actual password is part of the `Secrets` entity. The API allows you to create, delete, and update your passwords. You can retrieve individual passwords as well as a list of all your passwords.
  - name: User
    description: |
      User are entities with the ability to interact with the passbolt backend with their unique username and passwords. They are usually represented by one person. The User object returned by the API hence contains the relevant associated fields like `gpgkey`, `profile`, `role` etc.
  - name: Group
    description: Group of users
schemes:
  - https
paths:
  /auth/verify.json:
    get:
      summary: Fetches server's identity for verification
      description: |
        Returns server's public key with it's fingerprint. Useful when you want to send sensitive data to the server from a client. The sensitive data needs to be encrypted using this public key.
      tags:
        - Auth
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
                properties:
                  fingerprint:
                    type: string
                  keydata:
                    type: string
                    description: Server's PGP encrypted public key
  /auth/login.json:
    post:
      summary: Logs a user in
      description: |
        The same URL works for two login steps. The server recognises the step from the request payload and headers.

        Step 1. Encrypts a random string using server's public key and send to the server as request body in `server_verify_token`

        Step 2. After verification, the server responds back with a random token encrypted using client's public key in the header called `X-GPGAuth-User-Auth-Token`. 

        Step 3. Client then decrypts and sends the decrypted text in the request body in `user_token_result`.

        Step 4. Finally, the server verifies if the decrypted `user_token_result` matches with the original text and is still valid. Upon verification the server creates and returns "authenticated" cookies that can be used to make further requests.

        To know more about Passbolt's authentication. Please visit https://help.passbolt.com/tech/auth
      tags:
        - Auth
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - in: body
          name: auth
          schema:
            type: object
            required:
              - gpg_auth
            properties:
              gpg_auth:
                type: object
                properties:
                  keyid:
                    type: string
                    description: Fingerprint of the user's
                    example: 252B91CB28A96C6D67E8FC139020576F08D8B763
                  server_verify_token:
                    type: string
                    description: Token encrypted by the client using server's public key. This acts as a challenge that the server must solve to confirm it\'s integrity.
                  user_token_result:
                    type: string
                    description: Plaintext string that was decrypted using client's private key.
      responses:
        '200':
          description: OK
  /resources.json:
    get:
      description: Returns a list of your passwords. The passwords are returned sorted alphabetically by their name.
      summary: List all Passwords
      operationId: getPasswords
      tags:
        - Resource
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: contain
          description: Fields that must be included in the response. Takes a comma separated list.
          in: query
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - creator
              - favorite
              - modifier
              - permission
              - permissions.user.profile
              - permissions.group
              - secret
        - name: filter
          in: query
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - is-favorite
              - is-shared-with-group
              - is-owned-by-me
              - is-shared-with-me
              - has-id
        - name: order
          in: query
          description: How the result list should be sorted.
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - is-favorite
              - is-shared-with-group
              - is-owned-by-me
              - is-shared-with-me
              - has-id
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  code:
                    type: integer
                  message:
                    type: string
                  servertime:
                    type: integer
                    format: timestamp
                  status:
                    type: string
                  title:
                    type: string
                  url:
                    type: string
                    format: url
              body:
                type: array
                items:
                  $ref: '#/definitions/Resource'
        '403':
          description: |
            Authentication failure.
            --
            When the user making the request is not authenticated

    post:
      operationId: createPassword
      tags:
        - Resource
      summary: Creates a new Resource.
      description: Creates a new Resource with metadata and secrets.
      consumes:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - in: body
          name: resource
          schema:
            type: object
            required:
              - name
              - secrets
            properties:
              name:
                type: string
              description:
                type: string
                description: Description of the Resource.
              uri:
                type: string
                format: url
              secrets:
                type: array
                items:
                  properties:
                    user_id:
                      type: string
                      format: uuid
                    data:
                      type: string
                      description: Encrypted password string
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
        '403':
          description: |
            Forbidden
            --

  '/resources/{resourceId}.json':
    get:
      operationId: getPassword
      tags:
        - Resource
      summary: Find password by ID
      description: Returns a single password
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: resourceId
          in: path
          description: ID of the Resource to return
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                $ref: '#/definitions/Resource'
        '400':
          description: |
            Bad Request
            --
            The `resourceId` is not valid.
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A password with the given `resourceId` does not exist.
             - The current user does not have `READ` permission on the password

    put:
      tags:
        - Resource
      summary: Update an existing password
      description: |
        Updates the specified password by setting the values of the parameters passed. Any parameters not provided will be left unchanged.  

          This request accepts mostly the same arguments as the `Password` creation call.
      operationId: updatePassword
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: resourceId
          in: path
          description: ID of the password to update
          required: true
          type: string
          format: uuid
        - name: resource
          in: body
          description: Password data to update
          required: true
          schema:
            type: object
            properties:
              description:
                type: string
              name:
                type: string
              secrets:
                type: array
                items:
                  type: object
                  properties:
                    user_id:
                      type: string
                      format: uuid
                    data:
                      type: string
                      description: Encrypted password string
              uri:
                type: string
                format: url
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
            Some required parameters are missing
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A password with the given `resourceId` does not exist
             - The current user does not have sufficient permission on the password

    delete:
      operationId: deletePassword
      tags:
        - Resource
      summary: Deletes a password
      produces:
        - application/json
      description: |
        Deletes the password and also drops all the associated permissions.
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: resourceId
          in: path
          description: Password id to delete
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
            When `resourceId` is not a valid `UUID`
        '404':
          description: |
            Not Found
            --
            When either of the following is true
            - The `resourceId` does not exist.
            - The Resource is already deleted.
            - If the user does not have access to the Resource.
            - If the user does not have permission to delete the Resource.
        '500':
          description: |
            Server Error
            --
            if the resource could not be deleted for other reasons

  /users.json:
    get:
      description: Returns a list of your users. The users are returned sorted alphabetically by their name.
      summary: List all users
      operationId: getUsers
      tags:
        - User
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: contain
          description: Fields that must be included in the response. Takes a comma separated list.
          in: query
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - LastLoggedIn
        - name: filter
          in: query
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - search
              - has-groups
              - has-access
              - is-admin
        - name: order
          in: query
          description: How the result list should be sorted.
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - User.username
              - User.created
              - User.modified
              - Profile.first_name
              - Profile.last_name
              - Profile.created
              - Profile.modified
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  $ref: '#/definitions/UserFull'
        '403':
          description: |
            Authentication failure.
            --
            When the user making the request is not authenticated

    post:
      operationId: createUser
      tags:
        - User
      summary: Creates a new user.
      description: Creates a new user.
      consumes:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - in: body
          name: user
          schema:
            type: object
            required:
              - first_name
              - last_name
              - username
              - is_admin
            properties:
              first_name:
                type: string
                maxLength: 255
              last_name:
                type: string
                maxLength: 255
              username:
                type: string
                format: email
              is_admin:
                type: boolean
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
        '403':
          description: |
            Forbidden
            --

  '/users/{userId}.json':
    get:
      operationId: getUser
      tags:
        - User
      summary: Find user by ID
      description: Returns a single user
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: userId
          in: path
          description: ID of the user to return
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                $ref: '#/definitions/User'
        '400':
          description: |
            Bad Request
            --
            The `userId` is not valid.
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A user with the given `userId` does not exist.
             - The current user does not have `READ` permission on the user

    put:
      tags:
        - User
      summary: Update an existing user
      description: |
        Updates the specified user by setting the values of the parameters passed. Any parameters not provided will be left unchanged.  

          This request accepts mostly the same arguments as the `User` creation call.
      operationId: updateUser
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: userId
          in: path
          description: ID of the user to update
          required: true
          type: string
          format: uuid
        - name: user
          in: body
          description: User data to update
          required: true
          schema:
            type: object
            properties:
              description:
                type: string
              name:
                type: string
              secrets:
                type: array
                items:
                  type: object
                  properties:
                    user_id:
                      type: string
                      format: uuid
                    data:
                      type: string
                      description: Encrypted user string
              uri:
                type: string
                format: url
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
            Some required parameters are missing
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A user with the given `userId` does not exist
             - The current user does not have sufficient permission on the user

    delete:
      operationId: deleteUser
      tags:
        - User
      summary: Deletes a user
      produces:
        - application/json
      description: |
        Deletes the user and also drops all the associated permissions.
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: userId
          in: path
          description: User id to delete
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
            When `userId` is not a valid `UUID`
        '404':
          description: |
            Not Found
            --
            When either of the following is true
            - The `userId` does not exist.
            - The User is already deleted.
            - If the user does not have access to the user.
            - If the user does not have the permission to delete the user.
        '500':
          description: |
            Server Error
            --
            if the user could not be deleted for other reasons

  '/users/{userId}/dry-run':
    delete:
      tags:
        - User
      summary: Checks if a user can be deleted
      description: |
        A User can not be deleted if 
        * it's the sole owner of a shared Resource or
        * it's the sole manager of a Group or
        * it's the sole manager of a Group that is the sole owner of a shared Resource

        This endpoint is useful when you want to check and avoid any side effects of deleting a user.
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: userId
          in: path
          description: User id to check for deletion
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
            The User can be deleted safely
        '400':
          description: |
            Bad Request
            --
            Some of the validation checks failed. The User can not be deleted safely.

  /groups.json:
    get:
      description: Returns a list of your groups. The groups are returned sorted alphabetically by their name.
      summary: List all groups
      operationId: getGroups
      tags:
        - Group
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: contain
          description: Fields that must be included in the response. Takes a comma separated list.
          in: query
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - modifier
              - modifier.profile
              - user
              - group_user
              - my_group_user
        - name: filter
          in: query
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - has-users
              - has-managers
        - name: order
          in: query
          description: How the result list should be sorted.
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - Group.name
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  $ref: '#/definitions/Group'
        '403':
          description: |
            Authentication failure.
            --
            When the group making the request is not authenticated

    post:
      operationId: createGroup
      tags:
        - Group
      summary: Creates a new group.
      description: Creates a new group.
      consumes:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - in: body
          name: group
          schema:
            type: object
            required:
              - name
              - group_users
            properties:
              name:
                type: string
              group_users:
                type: array
                items:
                  type: object
                  properties:
                    user_id:
                      type: string
                      format: uuid
                    is_admin:
                      type: boolean
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
        '403':
          description: |
            Forbidden
            --

  '/groups/{groupId}.json':
    get:
      operationId: getGroup
      tags:
        - Group
      summary: Find group by ID
      description: Returns a single group
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: groupId
          in: path
          description: ID of the group to return
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                $ref: '#/definitions/Group'
        '400':
          description: |
            Bad Request
            --
            The `groupId` is not valid.
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A group with the given `groupId` does not exist.
             - The current group does not have `READ` permission on the group

    put:
      tags:
        - Group
      summary: Update an existing group
      description: |
        Updates the specified group by setting the values of the parameters passed. Any parameters not provided will be left unchanged.  

          This request accepts mostly the same arguments as the `Group` creation call.
      operationId: updateGroup
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: groupId
          in: path
          description: ID of the group to update
          required: true
          type: string
          format: uuid
        - in: body
          name: group
          schema:
            type: object
            required:
              - name
              - group_users
            properties:
              name:
                type: string
              group_users:
                type: array
                items:
                  type: object
                  properties:
                    user_id:
                      type: string
                      format: uuid
                    is_admin:
                      type: boolean
      responses:
        '200':
          description: |
            OK
            --
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                $ref: '#/definitions/Group'
        '400':
          description: |
            Bad Request
            --
            Some required parameters are missing
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A group with the given `groupId` does not exist
             - The current group does not have sufficient permission on the group
    delete:
      operationId: deleteGroup
      tags:
        - Group
      summary: Deletes a group
      produces:
        - application/json
      description: |
        Deletes the Group and also all the Resources that belong only to this group.
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: groupId
          in: path
          description: Group id to delete
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
            When `groupId` is not a valid `UUID`
        '404':
          description: |
            Not Found
            --
            When either of the following is true
            - The `groupId` does not exist.
            - The Group is already deleted.
            - If the user is neither a Group manager nor Admin.
        '500':
          description: |
            Server Error
            --
            if the group could not be deleted for other reasons

  '/groups/{groupId}/dry-run':
    put:
      tags:
        - Group
      summary: Checks if a group can be updated.
      description: |
        The endpoint performs all the validation checks required for a Group update. This is useful to determine if it's safe to update a Group. It returns a success response if the Group can be updated, on validation failures, the response will have the reason and suggestions for the failed checks.
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: groupId
          in: path
          description: Group id to check for update.
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
            The group can be updated safely
        '400':
          description: |
            Bad Request
            --
            If `groupId` is not a valid UUID.
        '403':
          description: |
            Forbidden
            --
            If the user making the request is neither the Group manager nor an Admin.
        '404':
          description: |
            Not Found
            --
            * No Group found for the given `groupId` or
            * The Group has been deleted.

    delete:
      tags:
        - Group
      summary: Checks if a group can be deleted
      description: A Group can not be deleted if it's the sole owner of a Resource. This endpoint is useful when you want to check and avoid any side effects of deleting a group.
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: groupId
          in: path
          description: Group id to check for deletion
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
            The Group can be deleted safely.
        '400':
          description: |
            Bad Request
            --
            The Group is the sole owner of a Resource and hence can not be deleted.

  /share/search-aros.json:
    get:
      tags:
        - Share
      summary: Get a list of Access Resource Objects or AROs
      description: Get a list of all the users/groups with whom an item can be shared
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: filter
          in: query
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - search
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  type: object
                  properties:
                    user_count:
                      type: number
                    id:
                      type: string
                      format: uuid
                    deleted:
                      type: boolean
                    created:
                      type: string
                      format: date
                    modified:
                      type: string
                      format: date
                    created_by:
                      type: string
                      format: uuid
                    modified_by:
                      type: string
                      format: uuid
  '/share/simulate/resource/{resourceId}.json':
    post:
      tags:
        - Share
      summary: Simulates sharing a password.
      description: |
        Simulates sharing a resource with a user and/or group. Useful for avoiding any side effects and checking the possible errors.
      operationId: simulateShare
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: resourceId
          in: path
          description: The identifier of the resource to dry run a share on
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
                properties:
                  changes:
                    type: object
                    properties:
                      added:
                        type: array
                        items:
                          type: object
                      changed:
                        type: array
                        items:
                          type: object
        '400':
          description: |
            Bad Request
            --
            If the `resourceId` is not a valid uuid
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A resource with the given `resourceId` does not exist
             - The resource is soft deleted
             - The user does not have access to the resource

  '/share/resource/{resourceId}.json':
    put:
      tags:
        - Share
      summary: Share a password
      description: |
        Shares a password.
      operationId: shareResource
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: resourceId
          in: path
          description: The identifier of the resource to dry run a share on
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
        '400':
          description: |
            Bad Request
            --
            If the `resourceId` is not a valid uuid
        '404':
          description: |
            Not Found
            --
            When either of the following is true
             - A resource with the given `resourceId` does not exist
             - The resource is soft deleted
             - The user does not have access to the resource

  '/permissions/resource/{resourceId}.json':
    get:
      tags:
        - Permission
      summary: TODO Summary
      description: TODO Description
      parameters:
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
        - name: resourceId
          in: path
          description: UUID of the password to check permissions for
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: |
            OK
            --
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    aco:
                      type: string
                    aco_foreign_key:
                      type: string
                      format: uuid
                    aro:
                      type: string
                    aro_foreign_key:
                      type: string
                      format: uuid
                    created:
                      type: string
                      format: datetime
                    group:
                      type: string
                    modified:
                      type: string
                      format: datetime
                    type:
                      type: number
  '/favorites/resource/{resourceId}.json':
    post:
      tags:
        - Favorite
      summary: Add Password to favourites
      description: Add the given password to list of favourites
      parameters:
        - name: resourceId
          in: path
          required: true
          type: string
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  user_id:
                    type: string
                    format: uuid
                  foreign_key:
                    type: string
                    format: uuid
                  foreign_model:
                    type: string
                    format: uuid
                  created:
                    type: string
                    format: datetime
                  modified:
                    type: string
                    format: datetime
        '404':
          description: |
            Not Found
            ---
             - If the resource id is not valid
             - If the resource does not exist
             - If the resource is soft deleted
             - If the user does not have access to the resource
  '/favorites/{favoriteId}.json':
    delete:
      tags:
        - Favorite
      summary: Delete a favorite entry
      description: Remove a password from the list of favorites
      parameters:
        - name: favoriteId
          in: path
          required: true
          type: string
          format: uuid
        - name: api-version
          in: query
          description: API Version to target for this request
          type: string
          default: v1
          enum:
            - v1
            - v2
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
        '400':
          description: |
            Bad Request
            --
            When the given `favoriteId` is not a valid uuid
        '404':
          description: |
            Not Found
            ---
             - If the favorite does not exist
  '/comments/resource/{resourceId}.json':
    get:
      tags:
        - Comment
      summary: List all comments on the record
      description: List all comments on an entity of `model` type and identified by `modelId`
      parameters:
        - name: resourceId
          in: path
          type: string
          format: uuid
          required: true
          description: ID of the resource to fetch comments for
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  $ref: '#/definitions/Comment'
        '400':
          description: |
            Bad Request
            ---
            When the given `resourceId` is not a valid UUID
        '404':
          description: |
            Not Found
            ---
            If a resource with the given `resourceId` is not found

    post:
      tags:
        - Comment
      summary: Add a comment to a resource
      description: Add a comment to a resource
      parameters:
        - name: resourceId
          in: path
          type: string
          format: uuid
          required: true
          description: ID of the resource to add comment to
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
        - in: body
          name: comment
          schema:
            type: object
            properties:
              content:
                type: string
                description: The comment text
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  $ref: '#/definitions/Comment'
        '400':
          description: |
            Bad Request
            ---
            When the given `resourceId` is not a valid UUID
        '404':
          description: |
            Not Found
            ---
            If a resource with the given `resourceId` is not found

  '/comments/{commentId}.json':
    put:
      tags:
        - Comment
      summary: Update a comment
      description: Update a comment
      parameters:
        - name: commentId
          in: path
          type: string
          format: uuid
          required: true
          description: ID of the comment to update
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
        - in: body
          name: comment
          schema:
            type: object
            properties:
              content:
                type: string
                description: The new content to update
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  $ref: '#/definitions/Comment'
        '400':
          description: |
            Bad Request
            ---
            When the given `resourceId` is not a valid UUID
        '404':
          description: |
            Not Found
            ---
            If a resource with the given `resourceId` is not found

    delete:
      tags:
        - Comment
      summary: Delete a comment
      description: Delete a comment
      parameters:
        - name: commentId
          in: path
          type: string
          format: uuid
          required: true
          description: ID of the comment to delete
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
        '400':
          description: |
            Bad Request
            ---
            When the given `resourceId` is not a valid UUID
        '404':
          description: |
            Not Found
            ---
            If a resource with the given `resourceId` is not found
            If the current user does not have enough permission to delete the comment

  /gpgkeys.json:
    get:
      tags:
        - GPG Key
      summary: List all the GPG keys
      description: Fetches a list of all your GPG keys
      parameters:
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  $ref: '#/definitions/GpgKey'

  '/gpgkeys/{keyId}.json':
    get:
      tags:
        - GPG Key
      summary: Find GPG key by ID
      description: Returns a single GPG key
      parameters:
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
        - name: keyId
          in: path
          type: string
          format: uuid
          required: true
          description: ID of the GPG key to fetch
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                $ref: '#/definitions/GpgKey'
        '400':
          description: |
            Bad Request
            ---
            If the given `keyId` is not a valid UUID
        '404':
          description: |
            Not Found
            ---
            If a GPGKey with the given `keyId` could not be found

  '/secrets/resource/{resourceId}.json':
    get:
      tags:
        - Secret
      summary: Get password for a given resource.
      description: Will return the secret password encoded with user's GPG key. This will need to be decrypted on the client end to get the actual password string.
      parameters:
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
        - name: resourceId
          in: path
          type: string
          format: uuid
          required: true
          description: ID of resource of which the password should be returned
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                type: object
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  created:
                    type: string
                    format: datetime
                  data:
                    type: string
                    description: PGP encrypted string containing the password string
                  modified:
                    type: string
                    format: datetime
                  resource_id:
                    type: string
                    format: uuid
                  user_id:
                    type: string
                    format: uuid

  /settings.json:
    get:
      tags:
        - Settings
      summary: List the user level settings
      parameters:
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                type: object
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
                properties:
                  app:
                    type: object
                    properties:
                      debug:
                        type: boolean
                      image_storage:
                        type: object
                        properties:
                          public_path:
                            type: string
                            format: uri
                      server_timezone:
                        type: string
                      session_timeout:
                        type: number
                      url:
                        type: string
                        format: url
                      version:
                        type: object
                        properties:
                          name:
                            type: string
                          number:
                            type: string
                  passbolt:
                    properties:
                      edition:
                        type: string
                        enum:
                          - ce
                          - pro
                      plugins:
                        type: object

  /roles.json:
    get:
      tags:
        - Role
      summary: List the available user roles
      parameters:
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: array
                items:
                  $ref: '#/definitions/Role'

  /healthcheck.json:
    get:
      tags:
        - Health Check
      summary: Perform a health check
      description: Return server status report
      parameters:
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: object
                properties:
                  ssl:
                    type: object
                  database:
                    type: object
                  application:
                    type: object
                  environment:
                    type: object
                  configFile:
                    type: object
                  core:
                    type: object
                  gpg:
                    type: object

  /healthcheck/status.json:
    get:
      tags:
        - Health Check
      summary: Get the health check status
      description: Return server status
      parameters:
        - name: api-version
          in: query
          type: string
          enum:
            - v1
            - v2
          default: v1
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              header:
                $ref: '#/definitions/ApiResponseHeader'
              body:
                type: string
                enum:
                  - OK


definitions:
  ApiResponseHeader:
    type: object
    properties:
      id:
        type: string
        format: uuid
      code:
        type: integer
      message:
        type: string
      servertime:
        type: integer
        format: timestamp
      status:
        type: string
      title:
        type: string
      url:
        type: string
        format: url
  ApiResponse:
    type: object
    properties:
      header:
        type: object
        $ref: '#/definitions/ApiResponseHeader'
      body:
        type: array
        items:
          type: object
  Avatar:
    type: object
    properties:
      url:
        type: object
        properties:
          medium:
            type: string
            format: uri
          small:
            type: string
            format: uri
  Comment:
    type: object
    properties:
      id:
        type: string
        format: uuid
      parent_id:
        type: string
        format: uuid
      foreign_key:
        type: string
        format: uuid
      foreign_model:
        type: string
      content:
        type: string
      created:
        type: string
        format: datetime
      modified:
        type: string
        format: datetime
      created_by:
        type: string
        format: uuid
      modified_by:
        type: string
        format: uuid
      user_id:
        type: string
        format: uuid
      creator:
        $ref: '#/definitions/User'
      children:
        type: array
        items:
          $ref: '#/definitions/Comment'
  Favorite:
    type: object
    properties:
      id:
        type: string
        format: uuid
      created:
        type: string
        format: date
      foreign_key:
        type: string
        format: uuid
      foreign_model:
        type: string
      modified:
        type: string
        format: date
      user_id:
        type: string
        format: uuid
  GpgKey:
    type: object
    properties:
      id:
        type: string
        format: uuid
      user_id:
        type: string
        format: uuid
      armored_key:
        type: string
      bits:
        type: number
      uid:
        type: string
      key_id:
        type: string
      fingerprint:
        type: string
      type:
        type: string
        enum:
          - RSA
          - ELGAMAL
          - DSA
          - ECC
          - ECDSA
          - DH
      expires:
        type: string
        format: date
      key_created:
        type: string
        format: date
      deleted:
        type: boolean
      created:
        type: string
        format: date
      modified:
        type: string
        format: date
  Group:
    type: object
    properties:
      id:
        type: string
        format: uuid
      name:
        type: string
      deleted:
        type: string
        format: date
      created:
        type: string
        format: date
      modified:
        type: string
        format: date
      created_by:
        type: string
        format: uuid
      modified_by:
        type: string
        format: uuid
      groups_users:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            group_id:
              type: string
              format: uuid
            created:
              type: string
              format: datetime
            is_admin:
              type: boolean
            user:
              $ref: '#/definitions/UserFull'
  Permission:
    type: object
    properties:
      id:
        type: string
        format: uuid
      aco:
        type: string
      aco_foreign_key:
        type: string
        format: uuid
      aro:
        type: string
      aro_foreign_key:
        type: string
        format: uuid
      created:
        type: string
        format: date
      modified:
        type: string
        format: date
      type:
        type: integer
  Profile:
    type: object
    properties:
      id:
        type: string
        format: uuid
      user_id:
        type: string
        format: uuid
      first_name:
        type: string
        maxLength: 255
      last_name:
        type: string
        maxLength: 255
      created:
        type: string
        format: date
      modified:
        type: string
        format: date
  Resource:
    type: object
    properties:
      id:
        type: string
        format: uuid
        description: |
          Unique ID of the password in `UUID` format
      created:
        type: string
        format: date
        description: |
          Datetime on when the password was created.
      created_by:
        type: string
        format: uuid
        description: |
          `ID` of the `User` who created the password in `UUID` format
      creator:
        $ref: '#/definitions/User'
      deleted:
        type: boolean
      description:
        type: string
      favorite:
        $ref: '#/definitions/Favorite'
      modified:
        type: string
        format: date
      modified_by:
        type: string
        format: uuid
      modifier:
        $ref: '#/definitions/User'
      name:
        type: string
      permission:
        $ref: '#/definitions/Permission'
      uri:
        type: string
        format: url
      username:
        type: string
  Role:
    type: object
    properties:
      id:
        type: string
        format: uuid
      name:
        type: string
      description:
        type: string
      created:
        type: string
        format: date
      modified:
        type: string
        format: date
  User:
    type: object
    properties:
      id:
        type: string
        format: uuid
      active:
        type: boolean
      created:
        type: string
        format: date
      deleted:
        type: boolean
      last_logged_in:
        type: string
        format: date
      modified:
        type: string
        format: date
      role_id:
        type: string
        format: uuid
      username:
        type: string
        format: email
  UserFull:
    type: object
    properties:
      id:
        type: string
        format: uuid
      role_id:
        type: string
        format: uuid
      username:
        type: string
        format: email
      active:
        type: boolean
      deleted:
        type: boolean
      created:
        type: string
        format: date
      modified:
        type: string
        format: date
      profile:
        $ref: '#/definitions/Profile'
      group_users:
        type: array
        items:
          $ref: '#/definitions/User'
      role:
        $ref: '#/definitions/Role'
      gpgkey:
        $ref: '#/definitions/GpgKey'
      last_logged_in:
        type: string
        format: date