Picus Security Authentication API

openapi: 3.2.0
info:
  title: Picus Customer Authentication API
  description: '<p class="body-1">You can access the simulation raw data using the Rest API. Scope of the API includes; Simulation list, Simulation Details, Threat/Objective/Action Results, Results mapped to MITRE ATTC&K and Unified Kill Chain frameworks, Detection Analysis Results, Validated Logs & Alerts with SIEM & EDR integration.</p>

    <p class="body-1">OAuth2 protocol is used to authorize Refresh/Access tokens. To obtain the API, you should generate a refresh token and then request an access token using the /v1/auth/token endpoint. The refresh token will be valid for 6 months, whereas the access token will be available for 2 hours. After getting the access token, add Authorization: Bearer {accessToken} to the header to request access to the below endpoints.</p>

    <p class="body-1">Endpoints returning data with a lot of load works with the pagination method. You can use the offset and limit parameters to get the correct page.</p>


    <i class="body-1">Your usage will be limited with your Picus license.</i>'
  version: '1.0'
servers:
- url: https://api.picussecurity.com/
security:
- Access-Token: []
tags:
- name: Authentication
paths:
  /v1/auth/refresh:
    post:
      security:
      - Access-Token: []
      description: 'This endpoint regenerates refresh token.

        Invalidates previous refresh/access token.

        When provided refresh token is expired, a new refresh token should be created from the application itself'
      tags:
      - Authentication
      summary: '# Regenerating refresh token'
      operationId: RegenerateRefreshTokenParam
      responses:
        '200':
          $ref: '#/components/responses/GenerateRefreshTokenInternalResponse'
        '401':
          $ref: '#/components/responses/unauthorizedErrorSwagger'
        '422':
          $ref: '#/components/responses/validationErrorSwagger'
        default:
          $ref: '#/components/responses/genericErrorSwagger'
      servers:
      - url: https://api.picussecurity.com/
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  x-go-name: RefreshToken
                  example: access_token (Getting from Settings / API Token / Generate Token)
  /v1/auth/token:
    post:
      description: 'OAuth2 protocol is used to authorize Refresh/Access tokens.

        To obtain the API, you should generate a refresh token and then request an access token using the /v1/auth/token endpoint.

        The refresh token will be valid for 6 months, whereas the access token will be available for 2 hours.

        After getting the access token, add Authorization: Bearer {accessToken} to the header to request access to the below endpoints.'
      tags:
      - Authentication
      summary: '# Getting access token for endpoints'
      operationId: AuthTokenParam
      responses:
        '200':
          $ref: '#/components/responses/AuthTokenResponse'
        '401':
          $ref: '#/components/responses/unauthorizedErrorSwagger'
        '422':
          $ref: '#/components/responses/validationErrorSwagger'
        default:
          $ref: '#/components/responses/genericErrorSwagger'
      security: []
      servers:
      - url: https://api.picussecurity.com/
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  x-go-name: RefreshToken
                  example: access_token (Getting from Settings / API Token / Generate Token)
components:
  responses:
    GenerateRefreshTokenInternalResponse:
      description: ''
      headers:
        created_at:
          description: When refresh token is created at
          schema:
            type: integer
            format: int64
        expired_at:
          description: When refresh token is expired at
          schema:
            type: integer
            format: int64
        id:
          description: Token Id
          schema:
            type: integer
            format: uint64
        is_expired:
          description: Token expiration flag
          schema:
            type: boolean
        name:
          description: Name
          schema:
            type: string
        token:
          description: Refresh Token
          schema:
            type: string
    unauthorizedErrorSwagger:
      description: unauthorizedErrorSwagger is represents unauthorized error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                x-go-name: Message
                example: unauthorized error
    AuthTokenResponse:
      description: AuthTokenResponse
      content:
        application/json:
          schema:
            type: object
            properties:
              expire_at:
                description: When access token is expired at
                type: integer
                format: int64
                x-go-name: ExpireAt
                example: 1650875751
              token:
                description: Access Token
                type: string
                x-go-name: Token
                example: access_token
    genericErrorSwagger:
      description: genericErrorSwagger is represents the erroneous cases
      content:
        application/json:
          schema:
            type: object
            properties:
              error_code:
                description: Error Code is optional. It is using for define specific error types.
                type: integer
                format: int64
                x-go-name: ErrorCode
                example: 1001
              errors:
                description: Errors are optional. If there are multiple error, this field gives details.
                type: object
                additionalProperties:
                  type: string
                x-go-name: Errors
                example: '["error1", "error2"]'
              message:
                description: Error Message that contains information about error
                type: string
                x-go-name: Message
    validationErrorSwagger:
      description: validationErrorSwagger is represents the erroneous cases
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                description: Validation Error List
                type: object
                additionalProperties:
                  type: string
                x-go-name: Errors
                example:
                  param: tag=max, param=25, given value=1000
              message:
                description: Message will be "validation error"
                type: string
                x-go-name: Message
                example: validation error
  securitySchemes:
    Access-Token:
      description: After getting the access token, type <i>Bearer accessToken</i> to the Value input box to request access to the below endpoints For example <i>Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9</i>
      type: apiKey
      name: Authorization
      in: header