SpecterOps Root CAs API

openapi: 3.2.0
info:
  title: BloodHound Root CAs API
  contact:
    name: BloodHound Enterprise Support
    url: https://bloodhound.specterops.io/
    email: support@specterops.io
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: v2
  description: This is the API that drives BloodHound Enterprise and Community Edition.
servers:
- url: /
  description: This is the base path for all endpoints, relative to the domain where the API is being hosted.
security:
- JWTBearerToken: []
- SignedRequest: []
  RequestDate: []
  HMACSignature: []
tags:
- name: Root CAs
paths:
  /api/v2/rootcas/{object_id}:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - $ref: '#/components/parameters/path.object-id'
    get:
      operationId: GetRootCaEntity
      summary: Get Root CA entity info
      description: Get info and counts for this Root CA node.
      tags:
      - Root CAs
      parameters:
      - $ref: '#/components/parameters/query.hydrate-counts'
      responses:
        '200':
          $ref: '#/components/responses/entity-info-query-results'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/rootcas/{object_id}/controllers:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - $ref: '#/components/parameters/path.object-id'
    get:
      operationId: GetRootCaEntityControllers
      summary: Get Root CA entity controllers
      description: Get a list, graph, or count of the principals that can control this Root CA.
      tags:
      - Root CAs
      parameters:
      - $ref: '#/components/parameters/query.entity.skip'
      - $ref: '#/components/parameters/query.entity.limit'
      - $ref: '#/components/parameters/query.entity.type'
      - $ref: '#/components/parameters/query.entity.sort-by'
      responses:
        '200':
          $ref: '#/components/responses/related-entity-query-results'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/rootcas/{object_id}/pki-hierarchy:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - $ref: '#/components/parameters/path.object-id'
    get:
      operationId: GetRootCaEntityPkiHierarchy
      summary: Get PKI hierarchy of Root CA entity
      description: Get a list, graph, or count of the PKI hierarchy of this Root CA.
      tags:
      - Root CAs
      parameters:
      - $ref: '#/components/parameters/query.entity.skip'
      - $ref: '#/components/parameters/query.entity.limit'
      - $ref: '#/components/parameters/query.entity.type'
      - $ref: '#/components/parameters/query.entity.sort-by'
      responses:
        '200':
          $ref: '#/components/responses/related-entity-query-results'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
components:
  responses:
    forbidden:
      description: '**Forbidden**

        This is most commonly caused by an authenticated client trying to

        access a resource that it does not have permission for.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 403
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: You do not have permission to access this resource
    internal-server-error:
      description: '**Internal Server Error**

        This is usually the result of either an unexpected database or application error.

        The client may try modifying or resending the request, but the error is likely not related to the client

        doing something wrong.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 500
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The request could not be handled due to an unexpected database error.
    unauthorized:
      description: '**Unauthorized**

        This endpoint failed an authentication requirement. Either the client tried to access

        a protected endpoint without being authenticated, or an auth validation failed (ex- invalid

        credentials or expired token).

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 401
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: login
              message: Unauthorized
    entity-info-query-results:
      description: '**OK**


        This response is polymorphic and depends on the type of entity being queried and whether

        the `count` param is true or not. All node types will return a `props` field with the graph node

        properties and a `kinds` field with the graph node kinds. If `count=true` the response will also include additional fields with integer counts.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  kinds:
                    type: array
                    items:
                      type: string
                  props:
                    type: object
                    additionalProperties:
                      type: object
    too-many-requests:
      description: '**Too Many Requests**

        The client has sent too many requests within a certain time window

        and tripped the rate limiting middleware.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 429
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: middleware
              message: Too many requests. Please try again later.
    not-found:
      description: '**Not Found**

        This error typically comes from operations where a valid ID was passed to the request

        to look up an entity but the entity could not be found.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 404
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The requested client could not be found.
    related-entity-query-results:
      description: '**OK**


        This endpoint returns a response, dependent upon which return type is requested by the `type` parameter.

        The only supported `type` parameter is `list`.

        While `list` is the only supported `type` parameter, the `graph` parameter can be used

        and will result in a different response structure then documented here.

        For those interested in using the undocumented graph type parameter, the response type is described in the schema

        `model.bh-graph.graph`.

        '
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/api.response.pagination'
            - title: list
              type: object
              properties:
                data:
                  type: array
                  items:
                    title: paged-node-list-entry
                    type: object
                    properties:
                      objectID:
                        type: string
                      name:
                        type: string
                      label:
                        type: string
                      kinds:
                        type: array
                        items:
                          type: string
    bad-request:
      description: '**Bad Request**

        This could be due to one of the following reasons:

        - JSON payload is missing or malformed

        - Path or query parameters are missing or invalid/malformed

        - The data sent is not valid (ex- sending a `string` in an `integer` field)

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 400
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The JSON payload could not be unmarshalled.
  schemas:
    api.params.query.limit:
      type: integer
      minimum: 0
      description: The limit of results requested by the client.
    api.error-detail:
      type: object
      properties:
        context:
          type: string
          description: The context in which the error took place
        message:
          type: string
          description: A human-readable description of the error
    api.params.query.sort-by:
      type: string
      description: 'Sort by column. Can be used multiple times; prepend a hyphen for descending order.

        See parameter description for details about which columns are sortable.

        '
    api.response.pagination:
      type: object
      properties:
        count:
          type: integer
          minimum: 0
          description: The total number of results.
        skip:
          $ref: '#/components/schemas/api.params.query.skip'
        limit:
          $ref: '#/components/schemas/api.params.query.limit'
    api.params.query.skip:
      type: integer
      minimum: 0
      description: The number of items to skip in a paginated response.
    api.error-wrapper:
      type: object
      description: ''
      properties:
        http_status:
          type: integer
          description: The HTTP status code
          minimum: 100
          maximum: 600
        timestamp:
          type: string
          format: date-time
          description: The RFC-3339 timestamp in which the error response was sent
        request_id:
          type: string
          format: uuid
          description: The unique identifier of the request that failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/api.error-detail'
          description: The error(s) that occurred from processing the request
  parameters:
    path.object-id:
      name: object_id
      description: The object id of the entity being operated on.
      in: path
      required: true
      schema:
        type: string
        description: The unique object identifier
    query.entity.sort-by:
      name: sort_by
      in: query
      description: 'Sort by column. Can be used multiple times; prepend a hyphen for descending order. Columns available

        for sorting are dependent on the entity object kind.

        '
      schema:
        $ref: '#/components/schemas/api.params.query.sort-by'
    query.hydrate-counts:
      description: Include counts of related entities. Default value is `true`.
      name: counts
      in: query
      schema:
        type: boolean
        default: true
    query.entity.skip:
      name: skip
      description: The number of entries to skip for pagination. Only available for `type=list`.
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
    query.entity.type:
      name: type
      description: 'The type of return data requested. If no type is provided, query will default to `list`.

        The only supported type is `list`, but the unsupported `graph` type can be used.

        Some entity query endpoints do not support the `graph` type. For those interested in

        using the undocumented graph type parameter, the response type is described in the schema

        `model.bh-graph.graph`.

        '
      in: query
      schema:
        type: string
        default: list
        enum:
        - list
        - graph
    query.entity.limit:
      name: limit
      description: The number of entries to limit in the response. Only available for `type=list`.
      in: query
      schema:
        type: integer
        minimum: 0
        default: 10
    header.prefer:
      name: Prefer
      description: Prefer header, used to specify a custom timeout in seconds using the wait parameter as per RFC7240. Passing in wait=-1 bypasses all timeout limits when the feature is enabled.
      in: header
      required: false
      schema:
        type: string
        default: wait=30
        pattern: ^wait=(-1|[0-9]+)$
  securitySchemes:
    JWTBearerToken:
      description: '`Authorization: Bearer $JWT_TOKEN`

        '
      type: http
      scheme: bearer
      bearerFormat: JWT
    SignedRequest:
      description: '`Authorization: bhesignature $TOKEN_ID`

        '
      type: apiKey
      name: Authorization
      in: header
    RequestDate:
      description: '`RequestDate: $RFC3339_DATETIME`

        '
      type: apiKey
      name: RequestDate
      in: header
    HMACSignature:
      description: '`Signature: $BASE64ENCODED_HMAC_SIGNATURE`

        '
      type: apiKey
      name: Signature
      in: header
x-tagGroups:
- name: Community & Enterprise
  tags:
  - Auth
  - Roles
  - Permissions
  - API Tokens
  - BloodHound Users
  - Collectors
  - Collection Uploads
  - Custom Node Management
  - API Info
  - Search
  - Audit
  - Config
  - Asset Isolation
  - Graph
  - Azure Entities
  - AD Base Entities
  - Computers
  - Containers
  - Domains
  - GPOs
  - AIA CAs
  - Root CAs
  - Enterprise CAs
  - NT Auth Stores
  - Cert Templates
  - OUs
  - AD Users
  - Groups
  - Data Quality
  - Datapipe
  - Cypher
  - OpenGraph (Experimental)
- name: Enterprise Only
  tags:
  - EULA
  - BHE Users
  - Analysis
  - Client Ingest
  - Clients
  - Jobs
  - Tasks
  - Events (Schedules)
  - Attack Paths
  - Risk Posture
  - Meta Entities
  - Alerts