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

# OpenAI Integration: API Key & Codex OAuth

> Inject your OpenAI API key or Codex OAuth credentials into agent requests so they can call GPT, DALL-E, and embeddings without handling the key.

## Overview

OneCLI injects your OpenAI credentials into requests to `api.openai.com` automatically. Agents make standard HTTP requests to the OpenAI API; the gateway adds the `Authorization: Bearer` header before forwarding.

This lets agents use GPT models, DALL-E, embeddings, and other OpenAI services without ever seeing or handling your credentials directly. For a comparison of supported LLM providers, see [LLM Providers](/integrations/llms).

## Auth methods

OneCLI supports two ways to authenticate with OpenAI:

| Method            | Best for                                   | Credential                              |
| ----------------- | ------------------------------------------ | --------------------------------------- |
| **API Key**       | Pay-per-use API access                     | `sk-proj-...` from the OpenAI Dashboard |
| **Codex (OAuth)** | ChatGPT subscription users (Plus/Pro/Team) | `auth.json` from `codex login`          |

## Setup: API Key

Use this method if you have an OpenAI API key with pay-per-use billing.

<Steps>
  <Step title="Get your API key">
    Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys) and create a new secret key. Copy it — you won't be able to see it again.
  </Step>

  <Step title="Add the key in OneCLI">
    Open the OneCLI dashboard, navigate to **Connections** > **LLMs**, and click **Add LLM Key**. Select **OpenAI**, make sure the **API Key** tab is selected, and paste your key.
  </Step>
</Steps>

**CLI alternative:**

```bash theme={null}
onecli secrets create --name "OpenAI" --type openai \
  --value "$OPENAI_API_KEY" --host-pattern api.openai.com
```

## Setup: Codex (OAuth)

Use this method to route requests through your ChatGPT subscription instead of paying per API call. This uses the same OAuth credentials that [OpenAI Codex CLI](https://github.com/openai/codex) uses.

<Steps>
  <Step title="Install Codex CLI">
    ```bash theme={null}
    npm install -g @openai/codex
    ```
  </Step>

  <Step title="Authenticate with device auth">
    ```bash theme={null}
    codex login --device-auth
    ```

    Follow the prompts to sign in with your ChatGPT account. Once authenticated, Codex saves your credentials to `~/.codex/auth.json`.
  </Step>

  <Step title="Add the credentials in OneCLI">
    Open the OneCLI dashboard, navigate to **Connections** > **LLMs**, and click **Add LLM Key**. Select **OpenAI**, switch to the **Codex (OAuth)** tab, and upload your `~/.codex/auth.json` file.
  </Step>
</Steps>

**CLI alternative:**

```bash theme={null}
onecli secrets create --name "Codex" --type openai \
  --file ~/.codex/auth.json --host-pattern api.openai.com
```

<Note>
  The gateway automatically refreshes the access token when it expires using the stored refresh token — no manual re-authentication needed.
</Note>

## How it works

1. Your credentials are encrypted and stored by OneCLI (AES-256-GCM at rest)
2. When an agent sends a request to `api.openai.com`, the gateway intercepts it
3. The gateway injects an `Authorization: Bearer {token}` header
4. The request is forwarded to OpenAI

For Codex OAuth, the gateway also monitors token expiry. When the access token expires, it automatically uses the refresh token to obtain a new one and persists the updated credentials — agents experience no interruption.

Agents never see the raw credentials. If you rotate your key or re-authenticate with Codex, update it in the dashboard and all agents pick up the new credentials automatically.

## Controlling access with rules

Use OneCLI's [rules engine](/guides/rules) to control how agents use your OpenAI credentials. For example, you can rate-limit requests, restrict agents to specific models by blocking certain paths, or flag high-cost operations for manual approval. Rules are evaluated before credential injection, so a blocked request never reaches OpenAI.