Opal Security requests API

openapi: 3.1.0
info:
  contact:
    email: hello@opal.dev
    name: Opal Team
    url: https://www.opal.dev/
  description: The Opal API is a RESTful API that allows you to interact with the Opal Security platform programmatically.
  title: Opal access-rules requests API
  version: '1.0'
servers:
- description: Production
  url: https://api.opal.dev/v1
tags:
- name: requests
  description: Operations related to requests
paths:
  /requests:
    get:
      summary: Get requests
      description: Returns a list of requests for your organization that is visible by the admin.
      operationId: getRequests
      parameters:
      - description: A start date filter for the events.
        examples:
          withDate:
            summary: Example with date
            value: 2021-11-01
          withDatetime:
            summary: Example with date and time in ISO 8601 datetime format.
            value: 2025-01-01 00:00:00+00:00
        explode: true
        in: query
        name: start_date_filter
        required: false
        schema:
          type: string
        style: form
      - description: An end date filter for the events.
        examples:
          withDate:
            summary: Example with date
            value: 2021-11-12
          withDatetime:
            summary: Example with date and time in ISO 8601 datetime format.
            value: 2025-01-01 00:00:00+00:00
        explode: true
        in: query
        name: end_date_filter
        required: false
        schema:
          type: string
        style: form
      - description: Filter requests by their requester ID.
        example: 37cb7e41-12ba-46da-92ff-030abe0450b1
        in: query
        name: requester_id
        required: false
        schema:
          format: uuid
          type: string
        style: form
      - description: Filter requests by their target user ID.
        example: 37cb7e41-12ba-46da-92ff-030abe0450b1
        in: query
        name: target_user_id
        required: false
        schema:
          format: uuid
          type: string
        style: form
      - description: Filter requests by the resource ID that was requested.
        example: 37cb7e41-12ba-46da-92ff-030abe0450b1
        in: query
        name: resource_id
        required: false
        schema:
          format: uuid
          type: string
        style: form
      - description: Filter requests by the group ID that was requested.
        example: 37cb7e41-12ba-46da-92ff-030abe0450b1
        in: query
        name: group_id
        required: false
        schema:
          format: uuid
          type: string
        style: form
      - description: The pagination cursor value.
        example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
        explode: true
        in: query
        name: cursor
        required: false
        schema:
          type: string
        style: form
      - description: Number of results to return per page. Default is 200.
        example: 200
        explode: true
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          maximum: 1000
        style: form
      - description: Boolean toggle for if it should only show pending requests.
        explode: true
        in: query
        name: show_pending_only
        required: false
        schema:
          type: boolean
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestList'
          description: The list of requests.
      security:
      - BearerAuth: []
      tags:
      - requests
    post:
      description: Create an access request
      operationId: createRequest
      requestBody:
        description: Resources to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequestInfo'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  id:
                    format: uuid
                    type: string
                    example: 4baf8423-db0a-4037-a4cf-f79c60cb67a5
          description: The resulting request.
      security:
      - BearerAuth: []
      tags:
      - requests
  /requests/relay:
    get:
      summary: Get requests via Relay
      description: Returns a paginated list of requests using Relay-style cursor pagination.
      operationId: getRequestsRelay
      deprecated: true
      parameters:
      - description: Number of results to return after the cursor. Use either first/after or last/before, not both.
        example: 10
        in: query
        name: first
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - description: Cursor to fetch results after. Used with 'first' for forward pagination.
        example: Y3Vyc29yOnYyOpK5MjAyMS0wMS0wN1QwNzo0MToyNy4xMTlaFjYwZmM2YmJlZjk4YzE1N2ZhNjFhYjk4Nw==
        in: query
        name: after
        required: false
        schema:
          type: string
      - description: Number of results to return before the cursor. Use either first/after or last/before, not both.
        example: 10
        in: query
        name: last
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - description: Cursor to fetch results before. Used with 'last' for backward pagination.
        example: Y3Vyc29yOnYyOpK5MjAyMS0wMS0wN1QwNzo0MToyNy4xMTlaFjYwZmM2YmJlZjk4YzE1N2ZhNjFhYjk4Nw==
        in: query
        name: before
        required: false
        schema:
          type: string
      - description: Filter requests by their status.
        example: PENDING
        in: query
        name: status
        required: false
        schema:
          $ref: '#/components/schemas/RequestStatusEnum'
      - description: Filter requests assigned to a specific user ID.
        example: 37cb7e41-12ba-46da-92ff-030abe0450b1
        in: query
        name: to
        required: false
        schema:
          format: uuid
          type: string
      - description: Filter requests made by a specific user ID.
        example: 37cb7e41-12ba-46da-92ff-030abe0450b1
        in: query
        name: from
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestConnection'
          description: A paginated list of requests using Relay-style cursor pagination.
      security:
      - BearerAuth: []
      tags:
      - requests
  /requests/{id}:
    get:
      summary: Get request by ID
      description: Returns a request by ID.
      operationId: getRequest
      parameters:
      - description: The ID of the request.
        example: 4baf8423-db0a-4037-a4cf-f79c60cb67a5
        explode: false
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
        style: simple
      responses:
        '200':
          description: The requested request object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Request'
      security:
      - BearerAuth: []
      tags:
      - requests
  /requests/{id}/approve:
    post:
      description: Approve an access request
      operationId: approveRequest
      parameters:
      - description: The ID of the request to approve
        in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Approval parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                level:
                  $ref: '#/components/schemas/RequestApprovalEnum'
                comment:
                  type: string
                  description: Optional comment for the approval
                  example: Approved after security review
              required:
              - level
      responses:
        '200':
          description: Request successfully approved
          content:
            application/json:
              schema:
                type: object
                properties:
                  request:
                    $ref: '#/components/schemas/Request'
      security:
      - BearerAuth: []
      tags:
      - requests
  /requests/{id}/deny:
    post:
      description: Deny an access request
      operationId: denyRequest
      parameters:
      - description: The ID of the request to deny
        in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Denial parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: Comment for the denial
                  example: Denied due to insufficient justification
                level:
                  $ref: '#/components/schemas/RequestApprovalEnum'
              required:
              - comment
      responses:
        '200':
          description: Request successfully denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  request:
                    $ref: '#/components/schemas/Request'
      security:
      - BearerAuth: []
      tags:
      - requests
  /requests/{id}/comments:
    get:
      description: Returns a list of comments for a specific request.
      operationId: getRequestComments
      parameters:
      - description: The ID of the request to get comments for
        in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: A list of comments associated with the specified request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestCommentList'
      security:
      - BearerAuth: []
      tags:
      - requests
    post:
      description: Comment on an access request
      operationId: createRequestComment
      parameters:
      - description: The ID of the request to comment on
        in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Comment parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: comment
              required:
              - comment
      responses:
        '200':
          description: Request successfully commented
          content:
            application/json:
              schema:
                type: object
                properties:
                  request:
                    $ref: '#/components/schemas/Request'
      security:
      - BearerAuth: []
      tags:
      - requests
components:
  schemas:
    Request:
      description: '# Request Object

        ### Description

        The `Request` object is used to represent a request.


        ### Usage Example

        Returned from the `GET Requests` endpoint.'
      example:
        id: 7c86c85d-0651-43e2-a748-d69d658418e8
        created_at: 2021-01-06 20:00:00+00:00
        updated_at: 2021-01-06 20:00:00+00:00
        requester_id: c86c85d-0651-43e2-a748-d69d658418e8
        target_user_id: r86c85d-0651-43e2-a748-d69d658418e8
        target_group_id: r86c85d-0651-43e2-a748-d69d658418e8
        status: pending
        reason: I need this resource.
        duration_minutes: 1440
        request_comments:
        - id: 7c86c85d-0651-43e2-a748-d69d658418e8
          created_at: 2021-01-06 20:00:00+00:00
          updated_at: 2021-01-06 20:00:00+00:00
          request_id: 4c86c85d-0651-43e2-a748-d69d658418e8
          user_id: c86c85d-0651-43e2-a748-d69d658418e8
          comment: This is a comment.
        reviewer_stages:
        - requestedRoleName: Admin
          requestedItemName: AWS Production Account
          stages:
          - stage: 1
            operator: AND
            reviewers:
            - id: 7c86c85d-0651-43e2-a748-d69d658418e8
              status: PENDING
          - stage: 2
            operator: OR
            reviewers:
            - id: 8d86c85d-0651-43e2-a748-d69d658418e9
              status: APPROVED
      properties:
        id:
          description: The unique identifier of the request.
          example: 7c86c85d-0651-43e2-a748-d69d658418e8
          format: uuid
          type: string
        created_at:
          description: The date and time the request was created.
          example: 2021-01-06 20:00:00+00:00
          format: date-time
          type: string
        updated_at:
          description: The date and time the request was last updated.
          example: 2021-01-06 20:00:00+00:00
          format: date-time
          type: string
        requester_id:
          description: The unique identifier of the user who created the request.
          example: 7c86c85d-0651-43e2-a748-d69d658418e8
          format: uuid
          type: string
        target_user_id:
          description: The unique identifier of the user who is the target of the request.
          example: 7c86c85d-0651-43e2-a748-d69d658418e8
          format: uuid
          type: string
        target_group_id:
          description: The unique identifier of the group who is the target of the request.
          example: 7c86c85d-0651-43e2-a748-d69d658418e8
          format: uuid
          type: string
        status:
          description: The status of the request.
          example: pending
          $ref: '#/components/schemas/RequestStatusEnum'
        reason:
          description: The reason for the request.
          example: I need access to the AWS account.
          type: string
        duration_minutes:
          description: The duration of the request in minutes.
          example: 120
          type: integer
        requested_items_list:
          description: The list of targets for the request.
          type: array
          items:
            $ref: '#/components/schemas/RequestedItem'
        custom_fields_responses:
          description: The responses given to the custom fields associated to the request
          type: array
          items:
            $ref: '#/components/schemas/RequestCustomFieldResponse'
        stages:
          deprecated: true
          description: The stages configuration for this request
          $ref: '#/components/schemas/RequestItemStages'
        reviewer_stages:
          description: The configured reviewer stages for every item in this request, or an error message if reviewers could not be loaded
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/RequestReviewerStages'
          - type: string
      required:
      - id
      - created_at
      - updated_at
      - requester_id
      - status
      - reason
    RequestConnection:
      type: object
      required:
      - edges
      - pageInfo
      - totalCount
      properties:
        edges:
          type: array
          items:
            $ref: '#/components/schemas/RequestEdge'
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        totalCount:
          type: integer
          description: The total number of items available
    RequestedItem:
      description: '# Requested Item Object

        ### Description

        The `RequestedItem` object is used to represent a request target item.


        ### Usage Example

        Returned from the `GET Requests` endpoint.'
      properties:
        resource_id:
          description: The ID of the resource requested.
          example: f454d283-ca87-4a8a-bdbb-df212eca5353
          format: uuid
          type: string
        group_id:
          description: The ID of the group requested.
          example: f454d283-ca87-4a8a-bdbb-df212eca5353
          format: uuid
          type: string
        access_level_name:
          description: The name of the access level requested.
          example: admin
          type: string
        access_level_remote_id:
          description: The ID of the access level requested on the remote system.
          example: arn:aws:iam::490306337630:role/SupportUser
          type: string
        name:
          description: The name of the target.
          example: Engineering Team
          type: string
        remote_id:
          description: The ID of the target on the remote system.
          example: arn:aws:iam::490306337630:role/SupportUser
          type: string
        remote_name:
          description: The name of the target on the remote system.
          example: SupportUser
          type: string
      example:
        resource_id: null
        group_id: f454d283-ca87-4a8a-bdbb-df212eca5353
        access_level_name: admin
        access_level_remote_id: arn:aws:iam::490306337630:role/SupportUser
        name: Engineering Team
    RequestCustomFieldResponse:
      properties:
        field_name:
          type: string
        field_type:
          example: SHORT_TEXT
          $ref: '#/components/schemas/RequestTemplateCustomFieldTypeEnum'
        field_value:
          oneOf:
          - type: string
            example: This is a response to a long text or short text or multi choice
          - type: boolean
            example: true
      required:
      - field_name
      - field_type
      - field_value
    RequestReviewerStages:
      description: The stages configuration for a request item
      type: object
      properties:
        access_level_name:
          description: The name of the access level requested.
          example: admin
          type: string
        access_level_remote_id:
          description: The ID of the access level requested on the remote system.
          example: arn:aws:iam::490306337630:role/SupportUser
          type: string
        item_name:
          description: The name of the requested item
          type: string
        item_id:
          description: The ID of the resource requested.
          example: f454d283-ca87-4a8a-bdbb-df212eca5353
          format: uuid
          type: string
        stages:
          description: The stages of review for this request
          type: array
          items:
            $ref: '#/components/schemas/RequestStage'
      required:
      - item_name
      - item_id
      - stages
    PageInfo:
      type: object
      required:
      - hasNextPage
      - endCursor
      - hasPreviousPage
      - startCursor
      properties:
        hasNextPage:
          type: boolean
          description: Whether there are more items after the end cursor
        endCursor:
          type: string
          description: The cursor to continue pagination forwards
        hasPreviousPage:
          type: boolean
          description: Whether there are more items before the start cursor
        startCursor:
          type: string
          description: The cursor to continue pagination backwards
    RequestTemplateCustomFieldTypeEnum:
      description: The type of the custom request field.
      enum:
      - SHORT_TEXT
      - LONG_TEXT
      - BOOLEAN
      - MULTI_CHOICE
      type: string
    RequestReviewer:
      description: A reviewer in a request stage
      type: object
      properties:
        id:
          description: The unique identifier of the reviewer
          type: string
          format: uuid
        full_name:
          description: The user's full name.
          example: Jake Barnes
          type: string
        status:
          description: The status of this reviewer's review
          type: string
          enum:
          - PENDING
          - APPROVED
          - REJECTED
      required:
      - id
      - status
    RequestCommentList:
      description: A paginated list of request comments
      type: object
      example:
        comments:
        - created_at: 2021-01-06 20:00:00+00:00
          request_id: 4c86c85d-0651-43e2-a748-d69d658418e8
          user_id: c86c85d-0651-43e2-a748-d69d658418e8
          comment: This is a comment.
      properties:
        comments:
          items:
            $ref: '#/components/schemas/RequestComment'
          type: array
      required:
      - comments
    ReviewStageOperator:
      description: The operator to apply to reviewers in a stage
      type: string
      enum:
      - AND
      - OR
    RequestStage:
      description: A stage in the request review process
      type: object
      properties:
        stage:
          description: The stage number
          type: integer
        operator:
          description: The operator to apply to reviewers in this stage
          $ref: '#/components/schemas/ReviewStageOperator'
        reviewers:
          description: The reviewers for this stage
          type: array
          items:
            $ref: '#/components/schemas/RequestReviewer'
      required:
      - stage
      - operator
      - reviewers
    RequestApprovalEnum:
      type: string
      enum:
      - REGULAR
      - ADMIN
      description: The decision level for the approval
      example: REGULAR
    CreateRequestInfo:
      description: All the information needed for creating a request
      properties:
        resources:
          type: array
          items:
            type: object
            properties:
              id:
                description: The ID of the resource requested. Should not be specified if group_id is specified.
                example: group283-ca87-4a8a-bdbb-df212eca5353
                format: uuid
                type: string
              access_level_remote_id:
                description: The ID of the access level requested on the remote system.
                example: arn:aws:iam::490306337630:role/SupportUser
                type: string
              access_level_name:
                description: The ID of the access level requested on the remote system. This field is deprecated and no longer required. We will populate based on the access_level_remote_id.
                example: arn:aws:iam::490306337630:role/SupportUser
                type: string
                deprecated: true
        groups:
          type: array
          items:
            type: object
            properties:
              id:
                description: The ID of the group requested. Should not be specified if resource_id is specified.
                example: f454d283-ca87-4a8a-bdbb-df212eca5353
                format: uuid
                type: string
              access_level_remote_id:
                description: The ID of the access level requested on the remote system.
                example: arn:aws:iam::490306337630:role/SupportUser
                type: string
              access_level_name:
                description: The ID of the access level requested on the remote system.
                example: arn:aws:iam::490306337630:role/SupportUser
                type: string
            required:
            - id
        target_user_id:
          description: The ID of the user to be granted access. Should not be specified if target_group_id is specified.
          example: userd283-ca87-4a8a-bdbb-df212eca5353
          format: uuid
          type: string
        target_group_id:
          description: The ID of the group the request is for.  Should not be specified if target_user_id is specified.
          example: userd283-ca87-4a8a-bdbb-df212eca5353
          format: uuid
          type: string
        reason:
          type: string
        support_ticket:
          type: object
          properties:
            ticketing_provider:
              $ref: '#/components/schemas/TicketingProviderEnum'
            remote_id:
              type: string
            identifier:
              type: string
            url:
              type: string
          required:
          - ticketing_provider
          - remote_id
          - identifier
          - url
        duration_minutes:
          description: The duration of the request in minutes. -1 represents an indefinite duration
          type: integer
          minimum: -1
        custom_metadata:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                $ref: '#/components/schemas/RequestTemplateCustomFieldTypeEnum'
              value:
                type: string
            required:
            - name
            - type
            - value
      required:
      - reason
      - duration_minutes
      - resources
      - groups
    RequestComment:
      description: '# Request Comment Object

        ### Description

        The `RequestComment` object is used to represent a comment on a request.


        ### Usage Example

        Returned from the `GET Requests` endpoint as part of a `Request` object.'
      example:
        created_at: 2021-01-06 20:00:00+00:00
        request_id: 4c86c85d-0651-43e2-a748-d69d658418e8
        user_id: c86c85d-0651-43e2-a748-d69d658418e8
        comment: This is a comment.
      properties:
        created_at:
          description: The date and time the comment was created.
          example: 2021-01-06 20:00:00+00:00
          format: date-time
          type: string
        request_id:
          description: The unique identifier of the request the comment is associated with.
          example: 7c86c85d-0651-43e2-a748-d69d658418e8
          format: uuid
          type: string
        user_id:
          description: The unique identifier of the user who made the comment.
          example: 7c86c85d-0651-43e2-a748-d69d658418e8
          format: uuid
          type: string
        user_full_name:
          description: The user's full name.
          example: Jake Barnes
          type: string
        user_email:
          description: The user's email address.
          example: jake.barnes@company.com
          type: string
        comment:
          description: The content of the comment.
          example: This is a comment.
          type: string
      required:
      - created_at
      - request_id
      - user_id
      - comment
    RequestItemStages:
      description: The stages configuration for a request item
      type: object
      deprecated: true
      properties:
        requestedRoleName:
          description: The name of the requested role
          type: string
        requestedItemName:
          description: The name of the requested item
          type: string
        stages:
          description: The stages of review for this request
          type: array
          items:
            $ref: '#/components/schemas/RequestStage'
      required:
      - requestedItemName
      - stages
    TicketingProviderEnum:
      description: The third party ticketing platform provider.
      enum:
      - JIRA
      - LINEAR
      - SERVICE_NOW
      example: LINEAR
      type: string
    RequestList:
      description: '# Request List

        ### Description

        The `RequestList` object is used to represent a list of requests.


        ### Usage Example

        Returned from the `GET Requests` endpoint.'
      example:
        requests:
        - id: 7c86c85d-0651-43e2-a748-d69d658418e8
          organization_id: w86c85d-0651-43e2-a748-d69d658418e8
          created_at: 2021-01-06 20:00:00+00:00
          updated_at: 2021-01-06 20:00:00+00:00
          requester_id: c86c85d-0651-43e2-a748-d69d658418e8
          target_user_id: r86c85d-0651-43e2-a748-d69d658418e8
          target_group_id: g86c85d-0651-43e2-a748-d69d658418e8
          status: pending
          reason: I need this resource.
          duration_minutes: 1440
          request_comments:
          - id: 4c86c85d-0651-43e2-a748-d69d658418e8
            created_at: 2021-01-06 20:00:00+00:00
            updated_at: 2021-01-06 20:00:00+00:00
            request_id: 7c86c85d-0651-43e2-a748-d69d658418e8
            user_id: c86c85d-0651-43e2-a748-d69d658418e8
            comment: This is a comment.
        cursor: eyJjcmVhdGVkX2F0IjoiMjAyMS0wMS0wNlQyMDo0NzowMFoiLCJ2YWx1ZSI6ImFkbWluIn0=
      properties:
        requests:
          description: The list of requests.
          type: array
          items:
            $ref: '#/components/schemas/Request'
        cursor:
          description: The cursor to use in the next request to get the next page of results.
          type: string
          example: eyJjcmVhdGVkX2F0IjoiMjAyMS0wMS0wNlQyMDo0NzowMFoiLCJ2YWx1ZSI6ImFkbWluIn0=
    RequestStatusEnum:
      description: '# Request Status

        ### Description

        The `RequestStatus` enum is used to represent the status of a request.


        ### Usage Example

        Returned from the `GET Requests` endpoint.'
      enum:
      - PENDING
      - APPROVED
      - DENIED
      - CANCELED
      type: string
    RequestEdge:
      type: object
      required:
      - node
      - cursor
      properties:
        node:
          $ref: '#/components/schemas/Request'
        cursor:
          type: string
          description: The cursor for this request edge
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http