Skip to main content
Available for Enterprise organizations where OpenAI model routing is enabled. 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 connect a user’s ChatGPT plan for Codex, see Connect Codex to ChatGPT. To track spend on your OpenAI direct API usage, see the AI cost usage API.

​
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.
  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

​
Add the integration with the CLI

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:

​
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:
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:
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 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:
The command never prints literal values or CEL expressions. To remove a header:
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

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.
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.
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.