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

# Headers

> Learn the custom headers Busha uses, what they do, and when to include them.

Busha API requests use a small set of custom headers in addition to standard HTTP headers such as `Content-Type`. This page explains the headers you will most commonly encounter and when to use them.

## Authorization

The `Authorization` header is required for most authenticated requests. It carries your business Secret API Key as a Bearer token.

```http theme={null}
Authorization: Bearer YOUR_SECRET_KEY
```

Use it for quotes, transfers, customers, recipients, balances, and most other business-owned resources. See [Make your first request](/guides/getting-started/make-first-request).

<Note>
  Pledge endpoints are the exception. They require a customer-scoped OAuth2 access token in this header instead of your business Secret Key. See [Pledges: Before you begin](/guides/pledges/introduction#before-you-begin).
</Note>

## X-BU-PROFILE-ID

Include `X-BU-PROFILE-ID` when a request should act on behalf of a specific customer rather than your business account.

```http theme={null}
X-BU-PROFILE-ID: CUS_abc123xyz789
```

This header is optional on most endpoints. Omit it and the request uses your business account by default. See [Customers](/overview/customers).

## X-BU-PUBLIC-KEY

Use `X-BU-PUBLIC-KEY` instead of `Authorization` for client-facing or lightly authenticated endpoints, especially payment requests.

```http theme={null}
X-BU-PUBLIC-KEY: pub_uibaidu930ani
```

Your public key is safe to expose in frontend code. Use it when creating or retrieving payment requests and when working with the Commerce SDK. See [Retrieve a payment request](/guides/payment-requests/retrieve-payment).

<Warning>
  Never use your Secret Key where a Public Key is expected, and never expose your Secret Key in client-side code.
</Warning>

## X-BU-Version

`X-BU-Version` lets you select a specific request and response schema version for endpoints that have changed over time.

```http theme={null}
X-BU-Version: 2025-07-11
```

This header is optional. If you omit it, Busha uses the default version for the endpoint. It is currently used on recipients endpoints and other endpoints that support versioned schemas. The older `X-BU-VERSION` header is deprecated and should not be used.

## X-Request-Id

`X-Request-Id` is a response header. Every API response includes a unique identifier for that call.

```http theme={null}
X-Request-Id: req_JfPBXEC5rLHc
```

Use it when you contact Busha support or need to debug a specific request. Request IDs are retained for 21 days. See [Request IDs](/guides/request-id/request-id).

## x-bu-signature

`x-bu-signature` is a webhook-specific header that Busha sends to your webhook endpoint. You do not send it to Busha.

```http theme={null}
x-bu-signature: <HMAC-SHA256 hash>
```

Use it to verify that an incoming webhook came from Busha. Compute an HMAC-SHA256 signature of the raw request body using your webhook secret, then compare it with this header value. See [Set up webhooks](/guides/webhooks/setup#verifying-webhook-signature).

## Quick reference

| Header            | Direction          | Required                    | Purpose                                   |
| ----------------- | ------------------ | --------------------------- | ----------------------------------------- |
| `Authorization`   | Request            | Yes (most endpoints)        | Secret Key or OAuth2 access token         |
| `X-BU-PROFILE-ID` | Request            | No                          | Scope a request to a specific customer    |
| `X-BU-PUBLIC-KEY` | Request            | Yes (Payment Requests only) | Public Key for client-facing endpoints    |
| `X-BU-Version`    | Request            | No                          | Select a specific endpoint schema version |
| `X-Request-Id`    | Response           | Always present              | Unique ID for support and debugging       |
| `x-bu-signature`  | Response (webhook) | Always present              | Verify webhook authenticity               |