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

# Headers

> Header requirements and options for the Obiguard API

Obiguard API accepts 4 kinds of headers for your requests:

|                                                           |            |                                       |
| :-------------------------------------------------------- | :--------- | :------------------------------------ |
| Obiguard Authentication Header                            | `Required` | For Obiguard auth                     |
| Provider Authentication Headers OR Cloud-Specific Headers | `Required` | For provider auth                     |
| Custom Headers                                            | `Optional` | To forward any other headers directly |

## Obiguard Authentication

### Obiguard API Key

<ResponseField name="x-obiguard-api-key / api_key / apiKey" required type="string">
  Authenticate your requests with your Obiguard API key. Obtain API key from the [Obiguard dashboard](https://app.obiguard.ai/api-keys).<br />
  Environment variable: `OBIGUARD_API_KEY`

  <Accordion title="Example">
    <Tabs>
      <Tab title="Python SDK">
        ```py Python {4} theme={null}
        from obiguard import Obiguard

        client = Obiguard(
          obiguard_api_key = "OBIGUARD_API_KEY" # defaults to os.environ.get("OBIGUARD_API_KEY")
        )
        ```
      </Tab>

      <Tab title="cURL">
        ```sh cURL {2} theme={null}
        curl https://gateway.obiguard.ai/v1/chat/completions \
          -H "x-obiguard-api-key: $OBIGUARD_API_KEY" \
        ```
      </Tab>
    </Tabs>
  </Accordion>
</ResponseField>

## Provider Authentication

In addition to the Obiguard API key, you must provide information about the AI provider you're using. There are **4** ways to do this:

### 1. Provider Slug + Auth

Useful if you do not want to save your API keys to Obiguard vault and make direct requests.

<ResponseField name="x-obiguard-provider / provider" type="string">
  Specifies the provider you're using (e.g., `openai`, `anthropic`, `vertex-ai`).<br />
  List of [Obiguard supported providers here](/integrations/llms).
</ResponseField>

<ResponseField name="Authorization" type="string">
  Pass the auth details for the specified provider as a `"Bearer $TOKEN"`.<br /><br />
  If your provider expects their auth with headers such as `x-api-key` or `api-key`, you can pass the token with the `Authorization` header directly and Obiguard will convert it into the provider-specific format.
</ResponseField>

<Accordion title="Example">
  <CodeGroup>
    ```sh cURL {3,4} theme={null}
    curl https://gateway.obiguard.ai/v1/chat/completions \
      -H "x-obiguard-api-key: $OBIGUARD_API_KEY" \
      -H "x-obiguard-provider: openai" \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
    ```

    ```py Python {5,6} theme={null}
    from obiguard import Obiguard

    client = Obiguard(
      api_key = "OBIGUARD_API_KEY", # defaults to os.environ.get("OBIGUARD_API_KEY")
      provider = "openai",
      Authorization = "Bearer OPENAI_API_KEY"
    )
    ```
  </CodeGroup>
</Accordion>

### 2. Virtual Key

<ResponseField name="x-obiguard-api-key / obiguard_api_key / obiguardApiKey" type="string">
  Save your provider auth on Obiguard and use a virtual key to directly make a call.
  This value is pass in the same field as Obiguard API key.
  [Docs](/virtual-keys)
</ResponseField>

<Accordion title="Example">
  <Tabs>
    <Tab title="Python SDK">
      ```py Python {4} theme={null}
      from obiguard import Obiguard

      client = Obiguard(
        obiguard_api_key="vk-obg***",  # Your Obiguard virtual key
      )
      ```
    </Tab>

    <Tab title="cURL">
      ```sh cURL {2} theme={null}
      curl https://gateway.obiguard.ai/v1/chat/completions \
        -H "x-obiguard-api-key: $OBIGUARD_API_KEY" \
      ```
    </Tab>
  </Tabs>
</Accordion>

### 4. Custom Host

<ResponseField name="x-obiguard-custom-host / custom_host / customHost" type="string">
  Specifies the base URL where you want to send your request
</ResponseField>

<ResponseField name="x-obiguard-provider / provider" type="string">
  Target provider that's availabe on your base URL. If you are unsure of which target provider to set, you can set `openai`.
</ResponseField>

<ResponseField name="Authorization" type="string">
  Pass the auth details for the specified provider as a `"Bearer $TOKEN"`.<br /><br />
  If your provider expects their auth with headers such as `x-api-key` or `api-key`, you can pass the token with the `Authorization` header directly and Obiguard will convert it into the provider-specific format.
</ResponseField>

<Accordion title="Example">
  <Tabs>
    <Tab title="Python SDK">
      ```py Python {5-7} theme={null}
      from obiguard import Obiguard

      client = Obiguard(
        obiguard_api_key="sk-obg***",  # Your Obiguard API key
        custom_host = "http://124.124.124.124/v1",
        provider = "openai",
        Authorization = "Bearer TOKEN"
      )
      ```
    </Tab>

    <Tab title="cURL">
      ```sh cURL {3-5} theme={null}
      curl https://gateway.obiguard.ai/v1/chat/completions \
        -H "x-obiguard-api-key: $OBIGUARD_API_KEY" \
        -H "x-obiguard-custom-host: http://124.124.124.124/v1" \
        -H "x-obiguard-provider: openai" \
        -H "Authorization: Bearer $TOKEN" \
      ```
    </Tab>
  </Tabs>
</Accordion>

## Custom Headers

You can pass any other headers your API expects by directly forwarding them without any processing by Obiguard.<br />
This is especially useful if you want to pass send sensitive headers.

### Forward Headers

<ResponseField name="x-obiguard-forward-headers / forward_headers / forwardHeaders" type="array of strings">
  Pass all the headers you want to forward directly in this array. ([Docs](/integrations/byollm#forward-sensitive-headers-securely))
</ResponseField>

<Accordion title="Example">
  <CodeGroup>
    ```sh cURL {4-6} theme={null}
    curl https://gateway.obiguard.ai/v1/chat/completions \
      -H "x-obiguard-api-key: $OBIGUARD_API_KEY" \
      -H "X-Custom-Header: ...."\
      -H "Another-Header: ....."\
      -H "x-obiguard-forward-headers: ['X-Custom-Header', 'Another-Header']" \
    ```

    ```py Python {6} theme={null}
    from obiguard import Obiguard

    client = Obiguard(
      obiguard_api_key = "OBIGUARD_API_KEY", # defaults to os.environ.get("OBIGUARD_API_KEY")
      X_Custom_Header = "....",
      Another_Header = "....",
      forward_headers = ['X_Custom_Header', 'Another_Header']
    )
    ```
  </CodeGroup>

  <Note>
    #### Python Usage

    With the Python SDK, you need to transform your headers to **Snake Case** and then include them while initializing the Obiguard client.
    Example: If you have a header of the format `X-My-Custom-Header`, it should be sent as `X_My_Custom_Header` in the SDK

    #### JavaScript Usage

    With the JS SDK, you need to transform your headers to **Camel Case** and then include them while initializing the Obiguard client.
    Example: If you have a header of the format `X-My-Custom-Header`, it should be sent as `xMyCustomHeader` in the SDK
  </Note>
</Accordion>

## Cloud-Specific Headers (`Azure`, `Google`, `AWS`)

Pass more configuration headers for `Azure OpenAI`, `Google Vertex AI`, or `AWS Bedrock`

### Azure

* `x-obiguard-azure-resource-name`, `x-obiguard-azure-deployment-id`, `x-obiguard-azure-api-version`, `Authorization`, `x-obiguard-azure-model-name`

### Google Vertex AI

* `x-obiguard-vertex-project-id`, `x-obiguard-vertex-region`, `X-Vertex-AI-LLM-Request-Type`

### AWS Bedrock

* `x-obiguard-aws-session-token`, `x-obiguard-aws-secret-access-key`, `x-obiguard-aws-region`, `x-obiguard-aws-session-token`

***

## List of All Headers

The following is a comprehensive list of headers that can be used when initializing the Obiguard client.

Obiguard adheres to language-specific naming conventions:

* **camelCase** for **JavaScript/Node.js** parameters
* **snake\_case** for **Python** parameters
* **hyphenated-keys** for **HTTP headers**

<Tabs>
  <Tab title="Python">
    | Parameter                                                                                                               | Type            | Key                                                                                |
    | :---------------------------------------------------------------------------------------------------------------------- | :-------------- | :--------------------------------------------------------------------------------- |
    | **API Key** Your Obiguard account's API Key.                                                                            | stringrequired  | `obiguard_api_key`                                                                 |
    | **Provider** The AI provider to use for your calls. ([supported providers](/integrations/llms#supported-ai-providers)). | string          | `provider`                                                                         |
    | **Base URL** You can edit the URL of the gateway to use.                                                                | string          | `base_url`                                                                         |
    | **Custom Host** Route to locally or privately hosted model by configuring the API URL with custom host                  | string          | `custom_host`                                                                      |
    | **Forward Headers** Forward sensitive headers directly to your model's API without any processing from Obiguard.        | array of string | `forward_headers`                                                                  |
    | **Azure OpenAI Headers** Configuration headers for Azure OpenAI that you can send separately                            | string          | `azure_resource_name` `azure_deployment_id` `azure_api_version` `azure_model_name` |
    | **Google Vertex AI Headers** Configuration headers for Vertex AI that you can send separately                           | string          | `vertex_project_id` `vertex_region`                                                |
    | **AWS Bedrock Headers** Configuration headers for Bedrock that you can send separately                                  | string          | `aws_access_key_id` `aws_secret_access_key` `aws_region` `aws_session_token`       |
  </Tab>

  <Tab title="REST Headers">
    | Parameter                                                                                                               | Type            | Header Key                                                                                                                        |
    | :---------------------------------------------------------------------------------------------------------------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
    | **API Key** Your Obiguard account's API Key.                                                                            | stringrequired  | `x-obiguard-api-key`                                                                                                              |
    | **Provider** The AI provider to use for your calls. ([supported providers](/integrations/llms#supported-ai-providers)). | string          | `x-obiguard-provider`                                                                                                             |
    | **Base URL** You can edit the URL of the gateway to use.                                                                | string          | Change the request URL                                                                                                            |
    | **Forward Headers** Forward sensitive headers directly to your model's API without any processing from Obiguard.        | array of string | `x-obiguard-forward-headers`                                                                                                      |
    | **Azure OpenAI Headers** Configuration headers for Azure OpenAI that you can send separately                            | string          | `x-obiguard-azure-resource-name`, `x-obiguard-azure-deployment-id`, `x-obiguard-azure-api-version`, `x-obiguard-azure-model-name` |
    | **Google Vertex AI Headers** Configuration headers for Vertex AI that you can send separately                           | string          | `x-obiguard-vertex-project-id`, `x-obiguard-vertex-region`                                                                        |
    | **AWS Bedrock Headers** Configuration headers for Bedrock that you can send separately                                  | string          | `x-obiguard-aws-session-token`, `x-obiguard-aws-secret-access-key`, `x-obiguard-aws-region`, `x-obiguard-aws-session-token`       |
  </Tab>
</Tabs>

### Using Headers

You can send these headers in multiple ways:

<Tabs>
  <Tab title="Python SDK">
    ```python Obiguard SDK theme={null}
    # Python - At initialization
    from obiguard import Obiguard

    client = Obiguard(
      obiguard_api_key="vk-obg***",  # Your Obiguard virtual key
    )

    # Python - At runtime
    completion = client.with_options(
      trace_id="your_trace_id",
      metadata={"_user": "user_12345"}
    ).chat.completions.create(
      messages=[{"role": "user", "content": "Hello!"}],
      model="gpt-4o"
    )
    ```
  </Tab>

  <Tab title="OpenAI SDK">
    ```python OpenAI SDK theme={null}
    # Python
    from openai import OpenAI
    from obiguard import OBIGUARD_GATEWAY_URL, createHeaders

    # At initialization
    client = OpenAI(
      api_key="OPENAI_API_KEY",
      base_url=OBIGUARD_GATEWAY_URL,
      default_headers=createHeaders({
        obiguard_api_key="vk-obg***",  # Your Obiguard virtual key
      })
    )

    # At runtime
    response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}]
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```sh REST API theme={null}
    curl https://gateway.obiguard.ai/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "x-obiguard-api-key: $OBIGUARD_API_KEY" \
      -d '{
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "Hello!"}]
      }'
    ```
  </Tab>
</Tabs>