SpecterOps API Tokens API

openapi: 3.2.0
info:
  title: BloodHound API Tokens 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: API Tokens
paths:
  /api/v2/tokens:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: ListAuthTokens
      summary: List Auth Tokens
      description: Get all auth tokens.
      tags:
      - API Tokens
      parameters:
      - name: user_id
        description: Provide a `user_id` to filter tokens by. Admin users may filter by any `user_id`. Non-admin users may only filter by their own `user_id` using `eq`.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.uuid'
      - name: sort_by
        description: 'Sortable columns are `user_id`, `client_id`, `name`, `last_access`, `created_at`, `updated_at`, `deleted_at`.

          '
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - name: name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: key
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: hmac_method
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: last_access
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.time'
      - name: id
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.uuid'
      - $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:
                      tokens:
                        type: array
                        items:
                          $ref: '#/components/schemas/model.auth-token'
        '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: CreateAuthToken
      summary: Create Token for User
      description: Create a new token to use with request signing based authentication for a given user.
      tags:
      - API Tokens
      requestBody:
        description: The request body for creating an auth token
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token_name:
                  type: string
                user_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.auth-token'
        '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/tokens/{token_id}:
    parameters:
    - name: token_id
      description: ID of auth token to delete.
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - $ref: '#/components/parameters/header.prefer'
    delete:
      operationId: DeleteAuthToken
      summary: Delete a User Token
      description: Delete a request signing token for a given user.
      tags:
      - API Tokens
      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'
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.
  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]+)$
  schemas:
    model.auth-token:
      allOf:
      - $ref: '#/components/schemas/model.components.uuid'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          user_id:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/null.uuid'
          name:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/null.string'
          key:
            type: string
            readOnly: true
          hmac_method:
            type: string
            readOnly: true
          last_access:
            type: string
            format: date-time
            readOnly: true
          created_by:
            description: The ID of the user who created the token
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/null.uuid'
    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
    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'
    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.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.uuid:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        valid:
          description: Valid is true if `uuid` is not `null`.
          type: boolean
    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`.

        '
  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