SpecterOps BloodHound Users API

openapi: 3.2.0
info:
  title: BloodHound Users 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: BloodHound Users
paths:
  /api/v2/bloodhound-users:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: ListUsers
      summary: List Users
      description: Gets all BloodHound user details.
      tags:
      - BloodHound Users
      parameters:
      - name: sort_by
        description: Sortable columns are first_name, last_name, email_address, principal_name, last_login, created_at, updated_at, deleted_at.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - name: first_name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: last_name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: email_address
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: principal_name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: id
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.uuid'
      - name: last_login
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.time'
      - $ref: '#/components/parameters/query.created-at'
      - $ref: '#/components/parameters/query.updated-at'
      - $ref: '#/components/parameters/query.deleted-at'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/model.user'
        '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'
    post:
      operationId: CreateUser
      summary: Create a New User
      description: Create a new BloodHound user.
      tags:
      - BloodHound Users
      requestBody:
        description: The request body for creating a user
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/api.requests.user.update'
              - $ref: '#/components/schemas/api.requests.user.set-secret'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.user'
        '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/bloodhound-users-minimal:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: ListUsersMinimal
      summary: List Users Minimal
      description: Returns all BloodHound user details without any sensitive data.
      tags:
      - BloodHound Users
      parameters:
      - name: sort_by
        description: Sortable columns are id, first_name, last_name and email_address.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - name: first_name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: last_name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: email_address
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: id
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.uuid'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/model.users-minimal'
        '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/bloodhound-users/{user_id}:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: user_id
      description: User ID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: GetUser
      summary: Get a user
      description: Get a BloodHound user's details.
      tags:
      - BloodHound Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.user'
        '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'
    patch:
      operationId: UpdateUser
      summary: Update a User
      description: Update a BloodHound user's properties'.
      tags:
      - BloodHound Users
      requestBody:
        description: The request body for updating a user
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.requests.user.update'
      responses:
        '200':
          $ref: '#/components/responses/no-content'
        '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'
    delete:
      operationId: DeleteUser
      summary: Delete a User
      description: Deletes an existing BloodHound user.
      tags:
      - BloodHound Users
      responses:
        '200':
          $ref: '#/components/responses/no-content'
        '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'
        default:
          $ref: '#/components/responses/error-response'
  /api/v2/bloodhound-users/{user_id}/secret:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: user_id
      description: User ID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    put:
      operationId: CreateOrSetUserSecret
      summary: Create or Set User Secret
      description: Create or set a user's secret to use as a login password.
      tags:
      - BloodHound Users
      requestBody:
        description: The request body for creating or setting a user secret
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.requests.user.set-secret'
      responses:
        '200':
          $ref: '#/components/responses/no-content'
        '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'
    delete:
      operationId: DeleteUserSecret
      summary: Expire User Secret
      description: Expire a user's secret to use as a login password.
      tags:
      - BloodHound Users
      responses:
        '200':
          $ref: '#/components/responses/no-content'
        '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/bloodhound-users/{user_id}/mfa:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: user_id
      description: User ID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      operationId: AddUserMfa
      summary: Enrolls user in multi-factor authentication
      tags:
      - BloodHound Users
      requestBody:
        description: The request body for enrolling a user in multi-factor authentication
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      qr_code:
                        type: string
                      totp_secret:
                        type: string
        '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'
    delete:
      operationId: RemoveUserMfa
      summary: Unenroll user from multi-factor authentication
      description: Unenrolls user from multi-factor authentication
      tags:
      - BloodHound Users
      requestBody:
        description: The request body for unenrolling a user from multi-factor authentication
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        $ref: '#/components/schemas/enum.mfa-activation-status'
        '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/bloodhound-users/{user_id}/mfa-activation:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: user_id
      description: User ID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: GetMfaActivationStatus
      summary: Returns MFA activation status for a user
      description: Returns multi-factor authentication status for a user
      tags:
      - BloodHound Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        $ref: '#/components/schemas/enum.mfa-activation-status'
        '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'
    post:
      operationId: ActivateUserMfa
      summary: Activates MFA for an enrolled user
      description: Activates multi-factor authentication for an enrolled user
      tags:
      - BloodHound Users
      requestBody:
        description: The request body for activating multi-factor authentication for an enrolled user
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                otp:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        $ref: '#/components/schemas/enum.mfa-activation-status'
        '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'
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
    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.
    no-content:
      description: '**No Content**

        This response will contain no response body.

        '
      content:
        text/plain:
          schema:
            type: string
          example: '[this request has no response data]'
    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.
    error-response:
      description: The standard error response wrapper.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
  schemas:
    model.user:
      allOf:
      - $ref: '#/components/schemas/model.components.uuid'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          saml_provider_id:
            readOnly: true
            deprecated: true
            description: Deprecated. Use sso_provider_id instead.
            allOf:
            - $ref: '#/components/schemas/null.int32'
          sso_provider_id:
            readOnly: true
            description: ID of the SSO provider for this user
            allOf:
            - $ref: '#/components/schemas/null.int32'
          AuthSecret:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/model.auth-secret'
          roles:
            type: array
            readOnly: true
            items:
              $ref: '#/components/schemas/model.role'
          first_name:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/null.string'
          last_name:
            $ref: '#/components/schemas/null.string'
          email_address:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/null.string'
          principal_name:
            type: string
            readOnly: true
          last_login:
            type: string
            readOnly: true
            format: date-time
          is_disabled:
            type: boolean
            readOnly: true
          eula_accepted:
            type: boolean
            readOnly: true
    model.components.int32.id:
      type: object
      properties:
        id:
          type: integer
          format: int32
          readOnly: true
          description: This is the unique identifier for this object.
    model.permission:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          authority:
            type: string
            readOnly: true
          name:
            type: string
            readOnly: true
    api.requests.user.update:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email_address:
          type: string
          format: email
        principal:
          type: string
        roles:
          type: array
          items:
            type: integer
            format: int32
        saml_provider_id:
          type: string
          deprecated: true
          description: Deprecated. Use sso_provider_id instead.
        sso_provider_id:
          allOf:
          - $ref: '#/components/schemas/null.int32'
          description: ID of the SSO provider for this user
        is_disabled:
          type: boolean
    model.users-minimal:
      allOf:
      - $ref: '#/components/schemas/model.components.uuid'
      - type: object
        properties:
          first_name:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/null.string'
          last_name:
            $ref: '#/components/schemas/null.string'
          email:
            type: string
            readOnly: true
    model.components.uuid:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: This is the unique identifier for this object.
    null.time:
      type: object
      properties:
        time:
          type: string
          format: date-time
          description: An RFC-3339 formatted string
        valid:
          description: Valid is true if `time` is not `null`.
          type: boolean
    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
    enum.mfa-activation-status:
      type: string
      description: The activation status of multi-factor authentication on a BloodHound user.
      enum:
      - activated
      - deactivated
      - pending
    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.

        '
    model.components.timestamps:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        deleted_at:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/null.time'
    null.int32:
      type: object
      properties:
        int32:
          type: integer
          format: int32
        valid:
          description: Valid is true if `int32` is not `null`.
          type: boolean
    model.auth-secret:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          digest_method:
            type: string
          expires_at:
            type: string
            format: date-time
          totp_activated:
            type: boolean
    model.role:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          name:
            type: string
            readOnly: true
          description:
            type: string
            readOnly: true
          permissions:
            type: array
            readOnly: true
            items:
              $ref: '#/components/schemas/model.permission'
    api.params.predicate.filter.string:
      type: string
      pattern: ^((eq|~eq|neq):)?[^:]+$
      description: 'Filter results by column string value. Valid filter predicates are `eq`, `~eq`, `neq`.

        '
    api.requests.user.set-secret:
      type: object
      properties:
        secret:
          type: string
        needs_password_reset:
          type: boolean
    api.params.predicate.filter.time:
      type: string
      pattern: ^((eq|neq|gt|gte|lt|lte):)?[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?([Zz]|-[0-9]{2}:[0-9]{2})$
      description: 'Filter results by column timestamp value formatted as an RFC-3339 string.

        Valid filter predicates are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`.

        '
    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
    null.string:
      type: object
      properties:
        string:
          type: string
        valid:
          description: Valid is true if `string` is not `null`
          type: boolean
    api.params.predicate.filter.uuid:
      type: string
      pattern: ^((eq|neq):)?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      description: 'Filter results by column string-formatted uuid value. Valid filter predicates are `eq`, `neq`.

        '
  parameters:
    query.updated-at:
      name: updated_at
      in: query
      description: Filter results by `updated_at` value. See filter schema details for valid predicates.
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.time'
    query.created-at:
      name: created_at
      in: query
      description: Filter results by `created_at` value. See filter schema details for valid predicates.
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.time'
    query.deleted-at:
      name: deleted_at
      in: query
      description: Filter results by `deleted_at` value. See filter schema details for valid predicates.
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.time'
    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