> ## 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 API Spec > Returns an Open API 3.0 compatible BloodHound API spec Applies to BloodHound Enterprise and CE ## OpenAPI ````yaml get /api/v2/spec 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/spec: parameters: - $ref: '#/components/parameters/header.prefer' get: tags: - API Info - Community - Enterprise summary: Get API Spec description: Returns an Open API 3.0 compatible BloodHound API spec operationId: GetApiSpec responses: '200': description: OK content: text/x-yaml: schema: type: string format: binary example: | openapi: 3.0.3 servers: - url: / ...[truncated example] '429': $ref: '#/components/responses/too-many-requests' '500': $ref: '#/components/responses/internal-server-error' 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]+)$ 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. 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. schemas: 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 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 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 ````