cerebrate/webroot/docs/openapi.yaml

openapi: 3.0.0
info:
  version: 1.3.0
  title: Cerebrate Project API
  description: |
    Cerebrate is an open-source platform meant to act as a trusted contact information provider and interconnection orchestrator for other security tools.

servers:
  - url: https://cerebrate.local

tags:
  - name: Users
    description: "Users enrolled in this Cerebrate instance."
  - name: Organisations
    description: "Organisations can be equivalent to legal entities or specific individual teams within such entities. Their purpose is to relate individuals to their affiliations and for release control of information using the Trust Circles."
  - name: Tags
    description: "Tags can be attached to entity to quickly classify them, allowing further filtering and searches."

paths:
  /api/v1/users/index:
    get:
      summary: "Get users list"
      operationId: getUsers
      tags:
        - Users
      responses:
        "200":
          $ref: "#/components/responses/UserListResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/users/view:
    get:
      summary: "Get information about the current user"
      operationId: viewUserMe
      tags:
        - Users
      responses:
        "200":
          $ref: "#/components/responses/UserResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/users/view/{userId}:
    get:
      summary: "Get information of a user by id"
      operationId: viewUserById
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          $ref: "#/components/responses/UserResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/users/add:
    post:
      summary: "Add user"
      operationId: addUser
      tags:
        - Users
      requestBody:
        $ref: "#/components/requestBodies/AddUserRequest"
      responses:
        "200":
          $ref: "#/components/responses/UserResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/users/edit:
    put:
      summary: "Edit current user"
      operationId: editUser
      tags:
        - Users
      requestBody:
        $ref: "#/components/requestBodies/EditUserRequest"
      responses:
        "200":
          $ref: "#/components/responses/UserResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/users/edit/{userId}:
    put:
      summary: "Edit current user"
      operationId: editUserById
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/userId"
      requestBody:
        $ref: "#/components/requestBodies/EditUserRequest"
      responses:
        "200":
          $ref: "#/components/responses/UserResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/users/delete/{userId}:
    delete:
      summary: "Delete user by ID"
      operationId: deleteUserById
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          $ref: "#/components/responses/UserResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/organisations/add:
    post:
      summary: "Add organisation"
      operationId: addOrganisation
      tags:
        - Organisations
      requestBody:
        $ref: "#/components/requestBodies/AddOrganisationRequest"
      responses:
        "200":
          $ref: "#/components/responses/OrganisationResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/organisations/edit/{organisationId}:
    put:
      summary: "Edit organisation"
      operationId: editOrganisation
      tags:
        - Organisations
      parameters:
        - $ref: "#/components/parameters/organisationId"
      requestBody:
        $ref: "#/components/requestBodies/EditOrganisationRequest"
      responses:
        "200":
          $ref: "#/components/responses/OrganisationResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/organisations/index:
    get:
      summary: "Get organisations"
      operationId: getOrganisations
      tags:
        - Organisations
      responses:
        "200":
          $ref: "#/components/responses/OrganisationListResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/organisations/delete/{organisationId}:
    delete:
      summary: "Delete organisation by ID"
      operationId: deleteOrganisationById
      tags:
        - Organisations
      parameters:
        - $ref: "#/components/parameters/organisationId"
      responses:
        "200":
          $ref: "#/components/responses/OrganisationResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/organisations/tag/{organisationId}:
    post:
      summary: "Tag organisation by ID"
      operationId: tagOrganisationById
      tags:
        - Organisations
      parameters:
        - $ref: "#/components/parameters/organisationId"
      requestBody:
        $ref: "#/components/requestBodies/TagOrganisationRequest"
      responses:
        "200":
          $ref: "#/components/responses/OrganisationResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/organisations/untag/{organisationId}:
    post:
      summary: "Remove organisation tag by ID"
      operationId: untagOrganisationById
      tags:
        - Organisations
      parameters:
        - $ref: "#/components/parameters/organisationId"
      requestBody:
        $ref: "#/components/requestBodies/UntagOrganisationRequest"
      responses:
        "200":
          $ref: "#/components/responses/OrganisationResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

  /api/v1/tags/index:
    get:
      summary: "Get tags list"
      operationId: getTags
      tags:
        - Tags
      responses:
        "200":
          $ref: "#/components/responses/TagListResponse"
        "403":
          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
        default:
          $ref: "#/components/responses/ApiErrorResponse"

components:
  schemas:
    # General
    UUID:
      type: string
      format: uuid
      maxLength: 36
      example: "c99506a6-1255-4b71-afa5-7b8ba48c3b1b"

    ID:
      type: integer
      format: int32
      example: 1

    DateTime:
      type: string
      format: datetime
      example: "2022-01-05T11:19:26+00:00"

    # Users
    Username:
      type: string
      example: "admin"

    User:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ID"
        uuid:
          $ref: "#/components/schemas/UUID"
        username:
          $ref: "#/components/schemas/Username"
        role_id:
          $ref: "#/components/schemas/ID"
        individual_id:
          $ref: "#/components/schemas/ID"
        disabled:
          type: boolean
        created:
          $ref: "#/components/schemas/DateTime"
        modified:
          $ref: "#/components/schemas/DateTime"
        organisation_id:
          $ref: "#/components/schemas/ID"

    UserList:
      type: array
      items:
        $ref: "#/components/schemas/User"

    # Individuals

    # Organisations
    OrganisationName:
      type: string

    OrganisationUrl:
      type: string

    OrganisationSector:
      type: string
      nullable: true

    OrganisationType:
      type: string
      nullable: true

    OrganisationContacts:
      type: string
      nullable: true

    OrganisationNationality:
      type: string
      nullable: true

    Organisation:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ID"
        uuid:
          $ref: "#/components/schemas/UUID"
        name:
          $ref: "#/components/schemas/OrganisationName"
        url:
          $ref: "#/components/schemas/OrganisationUrl"
        nationality:
          $ref: "#/components/schemas/OrganisationNationality"
        sector:
          $ref: "#/components/schemas/OrganisationSector"
        type:
          $ref: "#/components/schemas/OrganisationType"
        contacts:
          $ref: "#/components/schemas/OrganisationContacts"
        created:
          $ref: "#/components/schemas/DateTime"
        modified:
          $ref: "#/components/schemas/DateTime"
        tags:
          $ref: "#/components/schemas/TagList"
        aligments:
          $ref: "#/components/schemas/AligmentList"

    OrganisationList:
      type: array
      items:
        $ref: "#/components/schemas/Organisation"

    # Tags
    TagName:
      type: string
      example: "white"

    TagNamespace:
      type: string
      nullable: true
      example: "tlp"

    TagPredicate:
      type: string
      nullable: true

    TagValue:
      type: string
      nullable: true

    TagColour:
      type: string
      example: "FFFFFF"

    TagTextColour:
      type: string
      example: "white"

    Tag:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ID"
        name:
          $ref: "#/components/schemas/TagName"
        namespace:
          $ref: "#/components/schemas/TagNamespace"
        predicate:
          $ref: "#/components/schemas/TagPredicate"
        value:
          $ref: "#/components/schemas/TagValue"
        colour:
          $ref: "#/components/schemas/TagColour"
        text_colour:
          $ref: "#/components/schemas/TagTextColour"
        counter:
          type: integer
        created:
          $ref: "#/components/schemas/DateTime"
        modified:
          $ref: "#/components/schemas/DateTime"

    TagList:
      type: array
      items:
        $ref: "#/components/schemas/Tag"

    # Alignments
    Alignment:
      type: object

    AligmentList:
      type: array
      items:
        $ref: "#/components/schemas/Alignment"

    # Roles
    RoleName:
      type: string
      maxLength: 255
      example: "admin"

    Role:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ID"
        name:
          $ref: "#/components/schemas/RoleName"
        is_default:
          type: boolean
        perm_admin:
          type: boolean
        perm_sync:
          type: boolean
        perm_org_admin:
          type: boolean

    # Errors
    ApiError:
      type: object
      required:
        - message
        - url
        - code
      properties:
        message:
          type: string
        url:
          type: string
          example: "/api/v1/users"
        code:
          type: integer
          example: 500

    UnauthorizedApiError:
      type: object
      required:
        - message
        - url
        - code
      properties:
        message:
          type: string
          example: "Authentication failed. Please make sure you pass the API key of an API enabled user along in the Authorization header."
        url:
          type: string
          example: "/api/v1/users"
        code:
          type: integer
          example: 403

    MethodNotAllowedApiError:
      type: object
      required:
        - message
        - url
        - code
      properties:
        message:
          type: string
          example: "You do not have permission to use this functionality."
        url:
          type: string
          example: "/api/v1/users/index"
        code:
          type: integer
          example: 405

    NotFoundApiError:
      type: object
      required:
        - message
        - url
        - code
      properties:
        message:
          type: string
          example: "Invalid user"
        url:
          type: string
          example: "/api/v1/users/users/view/1234"
        code:
          type: integer
          example: 404

  parameters:
    userId:
      name: userId
      in: path
      description: "Numeric ID of the User"
      required: true
      schema:
        $ref: "#/components/schemas/ID"

    organisationId:
      name: organisationId
      in: path
      description: "Numeric ID of the Organisation"
      required: true
      schema:
        $ref: "#/components/schemas/ID"

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        The authorization is performed by using the following header in the HTTP requests:

            Authorization: YOUR_API_KEY

  requestBodies:
    # Users
    AddUserRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              individual_id:
                $ref: "#/components/schemas/ID"
              organisation_id:
                $ref: "#/components/schemas/ID"
              role_id:
                $ref: "#/components/schemas/ID"
              disabled:
                type: boolean
              username:
                $ref: "#/components/schemas/Username"
              password:
                type: string

    EditUserRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              individual_id:
                $ref: "#/components/schemas/ID"
              organisation_id:
                $ref: "#/components/schemas/ID"
              role_id:
                $ref: "#/components/schemas/ID"
              disabled:
                type: boolean
              username:
                $ref: "#/components/schemas/Username"
              password:
                type: string

    # Organisations
    AddOrganisationRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              uuid:
                $ref: "#/components/schemas/UUID"
              name:
                $ref: "#/components/schemas/OrganisationName"
              url:
                $ref: "#/components/schemas/OrganisationUrl"
              nationality:
                $ref: "#/components/schemas/OrganisationNationality"
              sector:
                $ref: "#/components/schemas/OrganisationSector"
              type:
                $ref: "#/components/schemas/OrganisationType"
              contacts:
                $ref: "#/components/schemas/OrganisationContacts"

    EditOrganisationRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              uuid:
                $ref: "#/components/schemas/UUID"
              name:
                $ref: "#/components/schemas/OrganisationName"
              url:
                $ref: "#/components/schemas/OrganisationUrl"
              nationality:
                $ref: "#/components/schemas/OrganisationNationality"
              sector:
                $ref: "#/components/schemas/OrganisationSector"
              type:
                $ref: "#/components/schemas/OrganisationType"
              contacts:
                $ref: "#/components/schemas/OrganisationContacts"

    TagOrganisationRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              tag_list:
                type: string
                description: "Stringified JSON array of the tag names to add."
                example: '["red"]'

    UntagOrganisationRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              tag_list:
                type: string
                description: "Stringified JSON array of the tag names to remove."
                example: '["red"]'

  responses:
    # Users
    UserResponse:
      description: "User response"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User"

    UserListResponse:
      description: "Users list response"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UserList"

    # Organisations
    OrganisationResponse:
      description: "Organisation response"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Organisation"

    OrganisationListResponse:
      description: "Organisations list response"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrganisationList"

    # Tags
    TagResponse:
      description: "Tag response"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Tag"

    TagListResponse:
      description: "Tags list response"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/TagList"

    # Errors
    ApiErrorResponse:
      description: "Unexpected API error"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"

    UnauthorizedApiErrorResponse:
      description: "Authentication failed. Please make sure you pass the API key of an API enabled user along in the Authorization header."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UnauthorizedApiError"

    MethodNotAllowedApiErrorResponse:
      description: "Method not allowed. Your User Role is not allowed to access this resource."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MethodNotAllowedApiError"

security:
  - ApiKeyAuth: []