openapi: 3.2.0
info:
  description: SafeBase API documentation.
  version: 1.4.1
  title: SafeBase API documentation Requests API
  contact:
    email: support@safebase.io
servers:
- url: https://app.safebase.io/api/ext/v1/rest
security:
- apiKey: []
tags:
- name: Requests
paths:
  /requests:
    get:
      tags:
      - Requests
      summary: Get access requests
      description: Gets all access requests
      operationId: getRequests
      parameters:
      - in: query
        name: status
        description: The status matching the requests to fetch
        schema:
          type: string
          enum:
          - pending
          - approved
          - declined
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: fe732619-4e7a-469b-b34a-d8bc4aaabfa9
                        firstName:
                          type: string
                          example: Sally
                        lastName:
                          type: string
                          example: Smith
                        email:
                          type: string
                          example: user@safebase.io
                        companyName:
                          type: string
                          example: SafeBase
                        status:
                          type: string
                          example: Pending
                        createdAt:
                          type: string
                          format: date-time
                          example: '2017-07-21T17:32:28Z'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - accounts:view
  /requests/{requestId}/approve:
    post:
      tags:
      - Requests
      summary: Approve access request
      description: "Approve access request\n\n Takes as input an object that must have one of two keys (not both):\n\n \n\n1. accountId - The account ID under which to approve the request \n\n2. account - Account information. The account will be created and the request will be approved under it \n\n**Idempotent Operation**: If the request has already been approved or declined, this endpoint will return a 409 Conflict response instead of an error. This allows for safe retries without side effects."
      operationId: approveRequest
      parameters:
      - name: requestId
        in: path
        description: ID of the request to approve
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accountId:
                  type: string
                  format: uuid
                account:
                  type: object
                  $ref: '#/components/schemas/CreateAccountPayload'
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    $ref: '#/components/schemas/AccountOutput'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '409':
          $ref: '#/components/responses/409'
      security:
      - apiKey:
        - accounts:edt
  /requests/{requestId}/decline:
    post:
      tags:
      - Requests
      summary: Decline access request
      description: 'Decline access request \n\n**Idempotent Operation**: If the request has already been approved or declined, this endpoint will return a 409 Conflict response instead of an error. This allows for safe retries without side effects.'
      operationId: declineRequest
      parameters:
      - name: requestId
        in: path
        description: ID of the request to decline
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  description: "This parameter allows you to send a custom message. It can be set to one of the following options: \n\n1. string - Sends a Safebase email with a custom message attached \n\n2. boolean - Set this parameter to 'true' to send a SafeBase email without any custom message \n\n3. undefined - If you do not wish to send a Safebase email, simply do not send this property as part of your request"
                  oneOf:
                  - type: string
                    description: Enter the 'string' option here
                  - type: boolean
                    description: Enter the 'boolean' option here
                  example: This is a custom message
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    $ref: '#/components/schemas/AccountOutput'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '409':
          $ref: '#/components/responses/409'
      security:
      - apiKey:
        - accounts:edit
components:
  schemas:
    CreateAccountPayload:
      type: object
      description: Account object that needs to be added to SafeBase
      required:
      - name
      properties:
        $ref: '#/paths/~1accounts/post/requestBody/content/application~1json/schema/properties/input/properties'
    AccountOutput:
      type: object
      properties:
        $ref: '#/paths/~1accounts/post/requestBody/content/application~1json/schema/properties/input/properties'
        id:
          type: string
          example: fe732619-4e7a-469b-b34a-d8bc4aaabfa9
        createdAt:
          type: string
          format: date-time
          example: '2017-07-21T17:32:28Z'
        numMembers:
          type: integer
          example: 4
        isNdaDone:
          description: Whether the NDA has been agreed to or not
          type: boolean
        lastSeen:
          description: The last time an account member has interacted with the Trust Center
          type: string | null
          format: date-time
          example: '2022-01-01T12:00:00Z'
    ApiResponseInvalidApiKeyOrMissingScope:
      type: object
      properties:
        statusCode:
          type: integer
          example: 403
        error:
          type: string
          example: forbidden
        message:
          type: string
          example: 'Invalid API key / Missing required scope(s): (missing scopes here)'
    ApiResponseInvalidRequest:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        error:
          type: string
          example: bad_request
        message:
          type: string
          example: Invalid request.
    ApiResponseNotFound:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: string
          example: not_found
        message:
          type: string
          example: Not found
    NdaProvider:
      type: string
      description: One of the available NDA options. If the ndaProvider field is not set, NDA provider will be set to the organization's default NDA provider.
      enum:
      - none
      - clickwrap
      - docusign
      - override
    ApiResponseConflict:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        errorCode:
          type: string
          example: request_already_handled
        errors:
          type: array
          items:
            type: string
          example:
          - Request has already been handled.
  responses:
    '400':
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseInvalidRequest'
    '405':
      description: Method not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseNotFound'
    '409':
      description: Conflict - Resource already handled
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseConflict'
    '404':
      description: Not found or no access
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseNotFound'
    '403':
      description: Invalid api key / missing scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseInvalidApiKeyOrMissingScope'
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-sb-api-key
      in: header