Opal Security apps 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 apps API
  version: '1.0'
servers:
- description: Production
  url: https://api.opal.dev/v1
tags:
- name: apps
  description: Operations related to apps
paths:
  /apps:
    get:
      summary: Get apps
      description: Returns a list of `App` objects.
      operationId: getApps
      parameters:
      - description: A list of app types to filter by.
        example:
        - OKTA_DIRECTORY
        - GIT_HUB
        explode: false
        in: query
        name: app_type_filter
        required: false
        schema:
          items:
            $ref: '#/components/schemas/AppTypeEnum'
          type: array
        style: form
      - description: An owner ID to filter by.
        example: 29827fb8-f2dd-4e80-9576-28e31e9934ac
        explode: true
        in: query
        name: owner_filter
        required: false
        schema:
          format: uuid
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppsList'
          description: A list of apps for your organization.
      security:
      - BearerAuth: []
      tags:
      - apps
  /apps/{app_id}:
    get:
      summary: Get app by ID
      description: Returns an `App` object.
      operationId: getApp
      parameters:
      - description: The ID of the app.
        example: 32acc112-21ff-4669-91c2-21e27683eaa1
        explode: true
        in: path
        name: app_id
        required: true
        schema:
          format: uuid
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
          description: The requested `App`.
      security:
      - BearerAuth: []
      tags:
      - apps
  /sync_errors:
    get:
      description: Returns a list of recent sync errors that have occurred since the last successful sync.
      operationId: getSyncErrors
      parameters:
      - description: The ID of the app to list sync errors for.
        example: 29827fb8-f2dd-4e80-9576-28e31e9934ac
        explode: false
        in: query
        name: app_id
        required: false
        schema:
          format: uuid
          type: string
        style: form
      - description: The ID of the resource to list sync errors for.
        example: 4baf8423-db0a-4037-a4cf-f79c60cb67a5
        explode: false
        in: query
        name: resource_id
        required: false
        schema:
          format: uuid
          type: string
        style: form
      - description: The ID of the group to list sync errors for.
        example: 9546209c-42c2-4801-96d7-9ec42df0f59c
        explode: false
        in: query
        name: group_id
        required: false
        schema:
          format: uuid
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SyncErrorList'
                type: array
          description: A list of sync errors.
      security:
      - BearerAuth: []
      tags:
      - apps
components:
  schemas:
    AppValidation:
      description: '# App validation object

        ### Description

        The `AppValidation` object is used to represent a validation check of an apps'' configuration and permissions.


        ### Usage Example

        List from the `GET Apps` endpoint.'
      example:
        key: iam:GetRole
        name: Opal's service account is missing the 'iam:GetRole' permission.
        usage_reason: Opal uses the 'iam:GetRole' permissions to view access to resources.
        details: 403 Google API Error. Service account is not authorized to access role assignments.
        severity: HIGH
        status: FAILED
        updated_at: 2021-01-06 20:00:00+00:00
      properties:
        key:
          description: The key of the app validation. These are not unique IDs between runs.
          example: iam:GetUser
          type: string
        name:
          description: The human-readable description of whether the validation has the permissions.
          example: Opal's service account is missing the 'iam:GetUser' description.
        usage_reason:
          description: The reason for needing the validation.
          example: Opal uses the 'iam:GetUser' permission to import users.
          type: string
        details:
          description: Extra details regarding the validation. Could be an error message or restrictions on permissions.
          example: 403 Google API Error. Service account is not authorized to access role assignments.
          type: string
        severity:
          $ref: '#/components/schemas/AppValidationSeverityEnum'
        status:
          $ref: '#/components/schemas/AppValidationStatusEnum'
        updated_at:
          description: The date and time the app validation was last run.
          example: 2021-01-06 20:00:00+00:00
          format: date-time
          type: string
      required:
      - key
      - name
      - status
      - severity
      - updated_at
    AppValidationStatusEnum:
      description: The status of an app validation.
      enum:
      - SUCCESS
      - FAILED
      example: FAILED
      type: string
    SyncError:
      description: '# SyncError Object

        ### Description

        The `SyncError` object is used to represent a sync error.


        ### Usage Example

        List from the `GET Sync Errors` endpoint.'
      example:
        app_id: b5a5ca27-0ea3-4d86-9199-2126d57d1fbd
        first_seen: 2022-07-14 06:59:59+00:00
        last_seen: 2022-08-23 04:32:46+00:00
        error_message: Failed to connect to the remote system - insufficient credentials.
      properties:
        first_seen:
          description: The time when this error was first seen.
          example: 2022-07-14 06:59:59+00:00
          type: string
          format: date-time
        last_seen:
          description: The time when this error was most recently seen.
          example: 2022-07-14 06:59:59+00:00
          type: string
          format: date-time
        error_message:
          description: The error message associated with the sync error.
          example: Failed to connect to the remote system - insufficient credentials.
          type: string
        app_id:
          description: The ID of the app that the error occured for.
          example: b5a5ca27-0ea3-4d86-9199-2126d57d1fbd
          format: uuid
          type: string
      required:
      - first_seen
      - last_seen
      - error_message
      type: object
    AppTypeEnum:
      description: The type of an app.
      enum:
      - ACTIVE_DIRECTORY
      - ANTHROPIC
      - AZURE_AD
      - AWS
      - AWS_SSO
      - CLICKHOUSE
      - COUPA
      - CURSOR
      - CUSTOM
      - CUSTOM_CONNECTOR
      - DATABRICKS
      - DATASTAX_ASTRA
      - DEVIN
      - DUO
      - GCP
      - GIT_HUB
      - GIT_LAB
      - GOOGLE_GROUPS
      - GOOGLE_WORKSPACE
      - GRAFANA
      - HUBSPOT
      - ILEVEL
      - INCIDENTIO
      - LDAP
      - MARIADB
      - MONGO
      - MONGO_ATLAS
      - MYSQL
      - NETSUITE
      - DATADOG
      - OKTA_CIAM
      - OKTA_DIRECTORY
      - OPENAI_PLATFORM
      - OPAL
      - ORACLE_FUSION
      - PAGERDUTY
      - POSTGRES
      - ROOTLY
      - SALESFORCE
      - SNOWFLAKE
      - SLACK
      - TABLEAU
      - TAILSCALE
      - TELEPORT
      - TWINGATE
      - VAULT
      - WORKDAY
      - ZENDESK
      example: OKTA_DIRECTORY
      type: string
    SyncErrorList:
      example:
        sync_errors:
        - app_id: b5a5ca27-0ea3-4d86-9199-2126d57d1fbd
          first_seen: 2022-07-14 06:59:59+00:00
          last_seen: 2022-08-23 04:32:46+00:00
          error_message: Failed to connect to the remote system - insufficient credentials.
        - app_id: b5a5ca27-0ea3-4d86-9199-2126d57d1fbd
          first_seen: 2023-04-24 06:59:59+00:00
          last_seen: 2024-08-21 04:32:46+00:00
          error_message: Resource not found.
      properties:
        sync_errors:
          items:
            $ref: '#/components/schemas/SyncError'
          type: array
      type: object
      required:
      - sync_errors
    App:
      description: '# App Object

        ### Description

        The `App` object is used to represent an app to an application.


        ### Usage Example

        List from the `GET Apps` endpoint.'
      example:
        app_id: f454d283-ca87-4a8a-bdbb-df212eca5353
        name: Okta Org
        description: Okta directory for the engineering team.
        admin_owner_id: 7c86c85d-0651-43e2-a748-d69d658418e8
        app_type: OKTA_DIRECTORY
      properties:
        app_id:
          description: The ID of the app.
          example: f454d283-ca87-4a8a-bdbb-df212eca5353
          format: uuid
          type: string
        name:
          description: The name of the app.
          example: Okta Org
          type: string
        description:
          description: A description of the app.
          example: Okta directory for the engineering team.
          type: string
        admin_owner_id:
          description: The ID of the owner of the app.
          example: 7c86c85d-0651-43e2-a748-d69d658418e8
          format: uuid
          type: string
        app_type:
          $ref: '#/components/schemas/AppTypeEnum'
        validations:
          description: Validation checks of an apps' configuration and permissions.
          items:
            $ref: '#/components/schemas/AppValidation'
          type: array
      required:
      - app_id
      - name
      - description
      - admin_owner_id
      - app_type
      type: object
    AppValidationSeverityEnum:
      description: The severity of an app validation.
      enum:
      - CRITICAL
      - HIGH
      - MEDIUM
      - LOW
      example: CRITICAL
      type: string
    AppsList:
      description: A list of apps.
      example:
      - app_id: f454d283-ca87-4a8a-bdbb-df212eca5353
        name: Okta Org
        description: Okta directory for the engineering team.
        admin_owner_id: 7c86c85d-0651-43e2-a748-d69d658418e8
        app_type: OKTA_DIRECTORY
      - app_id: 5247d283-ca87-4a8a-bdbb-df212eca1243
        name: Prod AWS Account
        description: Our production engineering account for AWS.
        admin_owner_id: aab485d-0651-43e2-a748-d69d6584123af
        app_type: AWS
      properties:
        apps:
          items:
            $ref: '#/components/schemas/App'
          type: array
      required:
      - apps
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http