Contraforce Service accounts API

openapi: 3.2.0
info:
  title: ContraForce Service accounts API
  description: ContraForce platform API for security operations management.
  version: '2.0'
tags:
- name: Service accounts
paths:
  /api/v2/service-accounts:
    get:
      tags:
      - Service accounts
      summary: List service accounts
      operationId: v2-list-service-accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfListOfServiceAccountDto'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
    post:
      tags:
      - Service accounts
      summary: Create service account
      operationId: v2-create-service-account
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceAccountRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceAccountCreatedDto'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/service-accounts/{id}:
    get:
      tags:
      - Service accounts
      summary: Get service account
      operationId: v2-get-service-account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceAccountDto'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
    put:
      tags:
      - Service accounts
      summary: Update service account
      operationId: v2-update-service-account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceAccountRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceAccountDto'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
    delete:
      tags:
      - Service accounts
      summary: Delete service account
      operationId: v2-delete-service-account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfboolean'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/service-accounts/{id}/disable:
    post:
      tags:
      - Service accounts
      summary: Disable service account
      operationId: v2-disable-service-account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceAccountDto'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/service-accounts/{id}/enable:
    post:
      tags:
      - Service accounts
      summary: Enable service account
      operationId: v2-enable-service-account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceAccountDto'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/service-accounts/{id}/credentials:
    post:
      tags:
      - Service accounts
      summary: Create service account credential
      operationId: v2-create-service-account-credential
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceAccountCredentialRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceAccountCredentialCreatedDto'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/service-accounts/{id}/credentials/{credentialId}/revoke:
    post:
      tags:
      - Service accounts
      summary: Revoke service account credential
      operationId: v2-revoke-service-account-credential
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceAccountCredentialDto'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/service-accounts/sentinel-ingest/deployment-card:
    post:
      tags:
      - Service accounts
      summary: Provision sentinel ingest credential
      operationId: v2-provision-sentinel-ingest-credential
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionSentinelIngestRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfSentinelIngestDeploymentCardDto'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
components:
  schemas:
    ServiceAccountCredentialDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        clientSecretPrefix:
          type:
          - 'null'
          - string
        status:
          $ref: '#/components/schemas/ServiceAccountCredentialStatus'
        expirationDate:
          type:
          - 'null'
          - string
          format: date-time
        lastUsedAt:
          type:
          - 'null'
          - string
          format: date-time
        createdAt:
          type: string
          format: date-time
        scopes:
          type:
          - 'null'
          - array
          items:
            type: string
          description: The API scopes granted to this credential.
      description: Represents a single API credential belonging to a service account.
    ResponseMeta:
      type: object
      properties:
        requestId:
          type:
          - 'null'
          - string
        timestamp:
          type:
          - 'null'
          - string
    CreateServiceAccountRequest:
      type: object
      properties:
        name:
          type:
          - 'null'
          - string
        description:
          type:
          - 'null'
          - string
        organizationalRole:
          $ref: '#/components/schemas/OrganizationalRole'
        workspaceAssignments:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/WorkspaceRoleAssignment'
        expirationDate:
          type:
          - 'null'
          - string
          format: date-time
        scopes:
          type:
          - 'null'
          - array
          items:
            type: string
          description: The granular API scopes granted to the initial credential.
    ApiResponseOfServiceAccountCredentialCreatedDto:
      type: object
      properties:
        data:
          description: Returned only when a credential is created. Contains the plaintext client secret which is shown once.
          $ref: '#/components/schemas/ServiceAccountCredentialCreatedDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ApiResponseOfServiceAccountDto:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ServiceAccountDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ApiProblemDetails:
      type: object
      properties:
        type:
          type:
          - 'null'
          - string
        title:
          type:
          - 'null'
          - string
        status:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          format: int32
        detail:
          type:
          - 'null'
          - string
        instance:
          type:
          - 'null'
          - string
        code:
          type:
          - 'null'
          - string
        requestId:
          type:
          - 'null'
          - string
        timestamp:
          type:
          - 'null'
          - string
        target:
          type:
          - 'null'
          - string
        errors:
          type:
          - 'null'
          - object
          additionalProperties:
            type: array
            items:
              type: string
      description: 'API extension of ProblemDetails that surfaces the stable error code,

        trace identifier, timestamp, optional target, and optional field-keyed validation

        error map alongside the RFC 7807 members.'
    ServiceAccountCreatedDto:
      type: object
      properties:
        clientId:
          type: string
          format: uuid
        clientSecret:
          type:
          - 'null'
          - string
        id:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        name:
          type:
          - 'null'
          - string
        description:
          type:
          - 'null'
          - string
        isActive:
          type: boolean
        isPlatformManaged:
          type: boolean
          description: 'True for platform-provisioned service accounts (e.g. the Sentinel Content Hub ingest SA). The UI

            badges these and hides destructive controls; the API rejects admin mutation of them.'
        organizationalRole:
          $ref: '#/components/schemas/OrganizationalRole'
        clientSecretPrefix:
          type:
          - 'null'
          - string
        credentialExpirationDate:
          type:
          - 'null'
          - string
          format: date-time
        workspaceAssignments:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/WorkspaceRoleAssignmentDto'
        credentials:
          type:
          - 'null'
          - array
          items:
            description: Represents a single API credential belonging to a service account.
            $ref: '#/components/schemas/ServiceAccountCredentialDto'
        lastUsedAt:
          type:
          - 'null'
          - string
          format: date-time
        createdAt:
          type: string
          format: date-time
        lastModifiedAt:
          type: string
          format: date-time
      description: Returned only on service account creation. Contains the plaintext client secret which is shown once.
    ServiceAccountDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        name:
          type:
          - 'null'
          - string
        description:
          type:
          - 'null'
          - string
        isActive:
          type: boolean
        isPlatformManaged:
          type: boolean
          description: 'True for platform-provisioned service accounts (e.g. the Sentinel Content Hub ingest SA). The UI

            badges these and hides destructive controls; the API rejects admin mutation of them.'
        organizationalRole:
          $ref: '#/components/schemas/OrganizationalRole'
        clientSecretPrefix:
          type:
          - 'null'
          - string
        credentialExpirationDate:
          type:
          - 'null'
          - string
          format: date-time
        workspaceAssignments:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/WorkspaceRoleAssignmentDto'
        credentials:
          type:
          - 'null'
          - array
          items:
            description: Represents a single API credential belonging to a service account.
            $ref: '#/components/schemas/ServiceAccountCredentialDto'
        lastUsedAt:
          type:
          - 'null'
          - string
          format: date-time
        createdAt:
          type: string
          format: date-time
        lastModifiedAt:
          type: string
          format: date-time
    SentinelIngestDeploymentCardDto:
      type: object
      properties:
        clientId:
          type: string
          description: The client id every playbook authenticates with (the managed service account id, shared org-wide).
          format: uuid
        clientSecret:
          type:
          - 'null'
          - string
          description: 'The client secret, shared across all of the organization''s workspaces. Returned on every provision so it

            can be reused when adding a workspace later; the same secret authenticates every playbook. Null only if

            the credential could not be resolved.'
        credentialAlreadyIssued:
          type: boolean
          description: 'True when the credential already existed before this call (this provisioning reused it rather than

            creating it). Informational; the secret is returned either way.'
        workspaces:
          type:
          - 'null'
          - array
          items:
            description: One onboarded workspace and the region-qualified ingest endpoint its playbook posts incidents to.
            $ref: '#/components/schemas/SentinelIngestWorkspaceDto'
          description: The workspaces onboarded by this call, each with the endpoint its Sentinel playbook posts to.
      description: 'The deployment card the portal shows after provisioning Sentinel Content Hub ingest: the shared client id

        and secret for the organization, plus each onboarded workspace and the endpoint its playbook posts to.'
    ServiceAccountCredentialStatus:
      enum:
      - Active
      - Revoked
    WorkspaceRoleAssignment:
      type: object
      properties:
        workspaceId:
          type: string
          format: uuid
        role:
          $ref: '#/components/schemas/WorkspaceRole'
    OrganizationalRole:
      enum:
      - Admin
      - UserAdmin
      - WorkspaceAdmin
      - AgentAdmin
      - Member
      - OrgContentOperator
      - OrgContentAdmin
    SentinelIngestWorkspaceDto:
      type: object
      properties:
        workspaceId:
          type: string
          format: uuid
        workspaceName:
          type:
          - 'null'
          - string
        ingestUrl:
          type:
          - 'null'
          - string
      description: One onboarded workspace and the region-qualified ingest endpoint its playbook posts incidents to.
    ApiResponseOfSentinelIngestDeploymentCardDto:
      type: object
      properties:
        data:
          description: 'The deployment card the portal shows after provisioning Sentinel Content Hub ingest: the shared client id

            and secret for the organization, plus each onboarded workspace and the endpoint its playbook posts to.'
          $ref: '#/components/schemas/SentinelIngestDeploymentCardDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ApiResponseOfboolean:
      type: object
      properties:
        data:
          type: boolean
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    WorkspaceRoleAssignmentDto:
      type: object
      properties:
        workspaceId:
          type: string
          format: uuid
        workspaceName:
          type:
          - 'null'
          - string
        role:
          $ref: '#/components/schemas/WorkspaceRole'
    ProvisionSentinelIngestRequest:
      type: object
      properties:
        workspaceIds:
          type:
          - 'null'
          - array
          items:
            type: string
            format: uuid
          description: The customer workspaces (ContraForce accounts) to onboard onto the ingest credential.
      description: 'Request to provision (or reuse) the platform-managed Sentinel Content Hub ingest credential and add one or

        more customer workspaces to it. The service-provider org is taken from the authenticated identity.'
    ApiResponseOfServiceAccountCredentialDto:
      type: object
      properties:
        data:
          description: Represents a single API credential belonging to a service account.
          $ref: '#/components/schemas/ServiceAccountCredentialDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ServiceAccountCredentialCreatedDto:
      type: object
      properties:
        clientId:
          type: string
          format: uuid
        clientSecret:
          type:
          - 'null'
          - string
        id:
          type: string
          format: uuid
        clientSecretPrefix:
          type:
          - 'null'
          - string
        status:
          $ref: '#/components/schemas/ServiceAccountCredentialStatus'
        expirationDate:
          type:
          - 'null'
          - string
          format: date-time
        lastUsedAt:
          type:
          - 'null'
          - string
          format: date-time
        createdAt:
          type: string
          format: date-time
        scopes:
          type:
          - 'null'
          - array
          items:
            type: string
          description: The API scopes granted to this credential.
      description: Returned only when a credential is created. Contains the plaintext client secret which is shown once.
    UpdateServiceAccountRequest:
      type: object
      properties:
        name:
          type:
          - 'null'
          - string
        description:
          type:
          - 'null'
          - string
        organizationalRole:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/OrganizationalRole'
        workspaceAssignments:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/WorkspaceRoleAssignment'
    WorkspaceRole:
      enum:
      - Owner
      - ContentAdmin
      - IncidentResponder
      - IncidentAnalyst
      - WorkspaceReader
    CreateServiceAccountCredentialRequest:
      type: object
      properties:
        expirationDate:
          type:
          - 'null'
          - string
          format: date-time
        scopes:
          type:
          - 'null'
          - array
          items:
            type: string
          description: The API scopes to grant to this credential.
      description: Request to create an additional credential for an existing service account.
    ApiResponseOfServiceAccountCreatedDto:
      type: object
      properties:
        data:
          description: Returned only on service account creation. Contains the plaintext client secret which is shown once.
          $ref: '#/components/schemas/ServiceAccountCreatedDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ApiResponseOfListOfServiceAccountDto:
      type: object
      properties:
        data:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/ServiceAccountDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.