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

# OpenAI direct API

> Set up a runner LLM integration that connects directly to the OpenAI API

> [!NOTE]
>
> Available for Enterprise organizations where OpenAI model routing is enabled. [Contact sales](https://ona.com/contact/sales) to learn more.

Use the OpenAI direct API integration when your organization wants OpenAI model requests to use its own OpenAI API key. You can also configure an OpenAI-compatible endpoint.

This page covers organization-level runner configuration.

To track spend on your OpenAI direct API usage, see the [AI cost usage API](https://ona.com/docs/ona/billing/cost-usage-api.md).

## Prerequisites

* Your organization has OpenAI model routing enabled.
* You have an enterprise runner configured in Ona.
* The runner can reach your OpenAI or OpenAI-compatible endpoint over HTTPS.
* You have an OpenAI API key or the credentials required by your OpenAI-compatible endpoint.

## Add the integration with the UI

1. Go to the [Runners settings page](https://app.ona.com/settings/runners).
2. Select the runner where you want to configure the OpenAI direct API.
3. Scroll to **LLM Providers**.
4. Click **Configure**.
5. Select **OpenAI**.
6. Use `https://api.openai.com/v1` for direct OpenAI, or enter your OpenAI-compatible endpoint.
7. Paste the API key into **API Key**.
8. Click **Create Integration**.

![OpenAI LLM integration form showing endpoint URL and API key fields](https://mintcdn.com/gitpod-13c83c2b/sggGGFHiP6Luo90h/images/openai-llm-integration.png?fit=max\&auto=format\&n=sggGGFHiP6Luo90h\&q=85\&s=220e6e4c91d0cf769065377572816683)

## Add the integration with the CLI

```bash theme={null}
gitpod runner config llm-integration create <runner-id> SUPPORTED_MODEL_OPENAI_AUTO https://api.openai.com/v1 <openai-api-key>
```

For an OpenAI-compatible endpoint, replace `https://api.openai.com/v1` with your endpoint URL. The URL may include a provider-specific path prefix and may end in `/v1`, `/v1/responses`, or `/v1/chat/completions`.

Ona preserves the prefix and completes requests to the required OpenAI API route.

To verify the integration:

```bash theme={null}
gitpod runner config llm-integration list
```

## Add custom request headers

Add custom request headers when your OpenAI-compatible gateway needs a routing value or details about the person who started the environment. For example, you can send a tenant name, email address, or employee ID with each model request.

Choose the header type based on the value you need:

* **Fixed value**: Sends the same value for every request.
* **User-specific value**: Builds the value from signed details about the environment creator when a Codex conversation starts.

### Send a fixed value

To add a literal header:

```bash theme={null}
gitpod runner config llm-integration set-header \
  <integration-id> \
  X-Gateway-Tenant \
  tenant-a \
  --type literal
```

`literal` is the default type, so `--type literal` is optional.

### Send a user-specific value

The following example reads an employee ID supplied by your identity provider:

```bash theme={null}
gitpod runner config llm-integration set-header \
  <integration-id> \
  X-Employee-ID \
  'env_id_claims.creator_idp_claims["employee_id"]' \
  --type cel-expression
```

User-specific values use Common Expression Language (CEL). Ona makes the signed environment token details available as `env_id_claims`. Common fields include `creator_id`, `creator_email`, and `creator_idp_claims`. See [environment token claims](https://ona.com/docs/ona/configuration/oidc.md#environment-tokens) for the full list.

User-specific values apply to Codex Agent conversations. Other agents send fixed headers but do not evaluate CEL expressions.

### Review or remove headers

List the configured names and effective types:

```bash theme={null}
gitpod runner config llm-integration list-headers <integration-id>
```

The command never prints literal values or CEL expressions. To remove a header:

```bash theme={null}
gitpod runner config llm-integration remove-header <integration-id> X-Employee-ID
```

If Ona cannot read the signed environment details or resolve an expression, the model request continues without the affected header. Other configured headers remain attached, and the conversation shows a configuration warning without exposing header values.

## Verify the integration

1. Create a new environment with the configured runner.
2. Start an agent that uses OpenAI model routing.
3. Confirm that the agent can answer a simple code question.

## Troubleshooting

> [accordion] OpenAI is not shown
>
> The OpenAI direct API integration is available only when OpenAI model routing is enabled for your organization. Contact your account manager if you expect this option to be available.

> [accordion] Authentication fails
>
> Verify that the API key is active and has access to the OpenAI endpoint you configured. If you use an OpenAI-compatible endpoint, confirm that the endpoint expects the same bearer-token authentication format.

> [accordion] Requests do not reach a custom endpoint
>
> Confirm that the runner can reach the endpoint over HTTPS. If the runner is in a private network, check outbound routing, firewall rules, and any proxy configuration required by your network.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.