> ## Documentation Index
> Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get self

> Get the currently authenticated requester details. For Community, this will only ever be valid for users. In Enterprise, this could be either a BloodHound user or a client (collector).


<img noZoom src="https://mintcdn.com/specterops/tTIczgde9H07oLXf/assets/enterprise-AND-community-edition-pill-tag.svg?fit=max&auto=format&n=tTIczgde9H07oLXf&q=85&s=ad49a576589f4d2a8081df77d07fdf56" alt="Applies to BloodHound Enterprise and CE" width="482" height="45" data-path="assets/enterprise-AND-community-edition-pill-tag.svg" />


## OpenAPI

````yaml get /api/v2/self
openapi: 3.0.3
info:
  title: BloodHound 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.

    Endpoint availability is denoted using the `Community` and `Enterprise`
    tags.


    Contact information listed is for BloodHound Enterprise customers. To get
    help with

    BloodHound Community Edition, please join our

    [Slack community](https://ghst.ly/BHSlack/).


    ## Authentication


    The BloodHound API supports two kinds of authentication: JWT bearer tokens
    and Signed Requests.

    For quick tests or one-time calls, the JWT used by your browser may be the
    simplest route. For

    more secure and long lived API integrations, the recommended option is
    signed requests.


    ### JWT Bearer Token


    The API will accept calls using the following header structure in the HTTP
    request:

    ```

    Authorization: Bearer $JWT_TOKEN

    ```

    If you open the Network tab within your browser, you will see calls against
    the API made utilizing

    this structure. JWT bearer tokens are supported by the BloodHound API,
    however it is recommended

    they only be used for temporary access. JWT tokens expire after a set amount
    of time and require

    re-authentication using secret credentials.


    ### Signed Requests


    Signed requests are the recommended form of authentication for the
    BloodHound API. Not only are

    signed requests better for long lived integrations, they also provide more
    security for the

    requests being sent. They provide authentication of the client, as well as
    verification of request

    integrity when received by the server.


    Signed requests consist of three main parts: The client token ID, the
    request timestamp, and a

    base64 encoded HMAC signature. These three pieces of information are sent
    with the request using

    the following header structure:


    ```

    Authorization: bhesignature $TOKEN_ID

    RequestDate: $RFC3339_DATETIME

    Signature: $BASE64ENCODED_HMAC_SIGNATURE

    ```


    To use signed requests, you will need to generate an API token. Each API
    token generated in the

    BloodHound API comes with two parts: The Token ID, which is used in the
    `Authorization` header,

    and the Token Key, which is used as part of the HMAC hashing process. The
    token ID should be

    considered as public (like a username) and the token key should be
    considered secret (like a

    password). Once an API token is generated, you can use the key to sign
    requests.


    For more documentation about how to work with authentication in the API,
    including examples

    of how to generate an API token in the BloodHound UI, please refer to this
    support doc:

    [Working with the BloodHound
    API](https://bloodhound.specterops.io/integrations/bloodhound-api/working-with-api).


    #### Signed Request Pseudo-code Example


    First, a digest is initiated with HMAC-SHA-256 using the token key as the
    digest key:

    ```python

    digester = hmac.new(sha256, api_token_key)

    ```


    OperationKey is the first HMAC digest link in the signature chain. This
    prevents replay attacks that

    seek to modify the request method or URI. It is composed of concatenating
    the request method and

    the request URI with no delimiter and computing the HMAC digest using the
    token key as the digest

    secret:

    ```python

    # Example: GET /api/v2/test/resource HTTP/1.1

    # Signature Component: GET/api/v2/test/resource

    digester.write(request_method + request_uri)


    # Update the digester for further chaining

    digester = hmac.New(sha256, digester.hash())

    ```


    DateKey is the next HMAC digest link in the signature chain. This encodes
    the RFC3339

    formatted datetime value as part of the signature to the hour to prevent
    replay

    attacks that are older than max two hours. This value is added to the
    signature chain

    by cutting off all values from the RFC3339 formatted datetime from the hours
    value

    forward:

    ```python

    # Example: 2020-12-01T23:59:60Z

    # Signature Component: 2020-12-01T23

    request_datetime = date.now()

    digester.write(request_datetime[:13])


    # Update the digester for further chaining

    digester = hmac.New(sha256, digester.hash())

    ```


    Body signing is the last HMAC digest link in the signature chain. This
    encodes the

    request body as part of the signature to prevent replay attacks that seek to
    modify

    the payload of a signed request. In the case where there is no body content
    the

    HMAC digest is computed anyway, simply with no values written to the
    digester:

    ```python

    if request.body is not empty:
      digester.write(request.body)
    ```


    Finally, base64 encode the final hash and write the three required headers
    before

    sending the request:

    ```python

    encoded_hash = base64_encode(digester.hash())

    request.header.write('Authorization', 'bhesignature ' + token_id)

    request.header.write('RequestDate', request_datetime)

    request.header.write('Signature', encoded_hash)

    ```
servers:
  - url: https://your-tenant.bloodhoundenterprise.io
    description: >-
      This is the base path for all endpoints, relative to the domain where the
      API is being hosted.
security:
  - JWTBearerToken: []
  - SignedRequest: []
    RequestDate: []
    HMACSignature: []
paths:
  /api/v2/self:
    parameters:
      - $ref: '#/components/parameters/header.prefer'
    get:
      tags:
        - Auth
        - Community
        - Enterprise
      summary: Get self
      description: >
        Get the currently authenticated requester details. For Community, this
        will only ever be valid for users. In Enterprise, this could be either a
        BloodHound user or a client (collector).
      operationId: GetSelf
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.response.authenticated-requester'
        '429':
          $ref: '#/components/responses/too-many-requests'
      security: []
components:
  parameters:
    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:
    api.response.authenticated-requester:
      type: object
      properties:
        data:
          oneOf:
            - $ref: '#/components/schemas/model.user'
            - $ref: '#/components/schemas/model.client'
    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
              format: date-time
              readOnly: true
            is_disabled:
              type: boolean
              readOnly: true
            eula_accepted:
              type: boolean
              readOnly: true
    model.client:
      allOf:
        - $ref: '#/components/schemas/model.components.uuid'
        - $ref: '#/components/schemas/model.components.timestamps'
        - type: object
          properties:
            name:
              type: string
              readOnly: true
            ip_address:
              type: string
              format: ipv4
              readOnly: true
            hostname:
              type: string
              format: hostname
              readOnly: true
            configured_user:
              type: string
              readOnly: true
            last_checkin:
              type: string
              format: date-time
              readOnly: true
            events:
              type: array
              readOnly: true
              items:
                $ref: '#/components/schemas/model.client-schedule'
            token:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/model.auth-token'
            current_job_id:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/null.int64'
            current_job:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/model.client-scheduled-job'
            completed_job_count:
              type: integer
              format: int32
              readOnly: true
            domain_controller:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/null.string'
            version:
              type: string
              readOnly: true
            user_sid:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/null.string'
            type:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/enum.client-type'
    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
    model.components.uuid:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: This is the unique identifier for this object.
    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'
    null.string:
      type: object
      properties:
        string:
          type: string
        valid:
          description: Valid is true if `string` is not `null`
          type: boolean
    model.client-schedule:
      allOf:
        - $ref: '#/components/schemas/model.components.int32.id'
        - $ref: '#/components/schemas/model.components.timestamps'
        - type: object
          properties:
            client_id:
              type: string
              format: uuid
              readOnly: true
            rrule:
              type: string
            session_collection:
              type: boolean
            local_group_collection:
              type: boolean
            ad_structure_collection:
              type: boolean
            cert_services_collection:
              type: boolean
            ca_registry_collection:
              type: boolean
            dc_registry_collection:
              type: boolean
            all_trusted_domains:
              type: boolean
            next_scheduled_at:
              type: string
              format: date-time
              readOnly: true
            ous:
              type: array
              items:
                type: string
            domains:
              type: array
              items:
                type: string
    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'
    null.int64:
      type: object
      properties:
        int64:
          type: integer
          format: int64
        valid:
          description: Valid is true if `int64` is not `null`.
          type: boolean
    model.client-scheduled-job:
      allOf:
        - $ref: '#/components/schemas/model.components.int64.id'
        - $ref: '#/components/schemas/model.components.timestamps'
        - type: object
          properties:
            client_id:
              type: string
              format: uuid
              readOnly: true
            client_name:
              type: string
              readOnly: true
            event_id:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/null.int32'
            status:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/enum.job-status'
            statusMessage:
              type: string
              readOnly: true
            start_time:
              type: string
              format: date-time
              readOnly: true
            end_time:
              type: string
              format: date-time
              readOnly: true
            log_path:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/null.string'
            session_collection:
              type: boolean
            local_group_collection:
              type: boolean
            ad_structure_collection:
              type: boolean
            cert_services_collection:
              type: boolean
            ca_registry_collection:
              type: boolean
            dc_registry_collection:
              type: boolean
            all_trusted_domains:
              type: boolean
            domain_controller:
              $ref: '#/components/schemas/null.string'
            event_title:
              type: string
              readOnly: true
            last_ingest:
              type: string
              format: date-time
              readOnly: true
            ous:
              type: array
              readOnly: true
              items:
                type: string
            domains:
              type: array
              readOnly: true
              items:
                type: string
            domain_results:
              type: array
              readOnly: true
              items:
                $ref: '#/components/schemas/model.domain-collection-result'
    enum.client-type:
      type: string
      description: This enum describes the collector client type.
      enum:
        - sharphound
        - azurehound
        - openhound
    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
    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
    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
    null.uuid:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        valid:
          description: Valid is true if `uuid` is not `null`.
          type: boolean
    model.components.int64.id:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: This is the unique identifier for this object.
    enum.job-status:
      type: integer
      description: |
        This enum describes the current status of a Job. Values are:
        - `-1` Invalid
        - `0` Ready
        - `1` Running
        - `2` Complete
        - `3` Canceled
        - `4` Timed Out
        - `5` Failed
        - `6` Ingesting
        - `7` Analyzing
        - `8` Partially Complete
      enum:
        - -1
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
    model.domain-collection-result:
      allOf:
        - $ref: '#/components/schemas/model.components.int64.id'
        - $ref: '#/components/schemas/model.components.timestamps'
        - type: object
          properties:
            job_id:
              type: integer
              format: int64
            domain_name:
              description: Name of the domain that was enumerated
              type: string
            success:
              description: >-
                A boolean value indicating whether the domain enumeration
                succeeded
              type: boolean
            message:
              description: A status message for a domain enumeration result
              type: string
            user_count:
              description: A count of users enumerated
              type: integer
            group_count:
              description: A count of groups enumerated
              type: integer
            computer_count:
              description: A count of computers enumerated
              type: integer
            gpo_count:
              description: A count of gpos enumerated
              type: integer
            ou_count:
              description: A count of ous enumerated
              type: integer
            container_count:
              description: A count of containers enumerated
              type: integer
            aiaca_count:
              description: A count of aiacas enumerated
              type: integer
            rootca_count:
              description: A count of rootcas enumerated
              type: integer
            enterpriseca_count:
              description: A count of enterprisecas enumerated
              type: integer
            ntauthstore_count:
              description: A count of ntauthstores enumerated
              type: integer
            certtemplate_count:
              description: A count of certtemplates enumerated
              type: integer
            deleted_count:
              description: A count of deleted objects enumerated
              type: integer
  responses:
    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.
  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

````