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

# Use OpenAI API Keys and Codex OAuth With AI Agents

> Give agents OpenAI access with an API key or your ChatGPT plan via Codex OAuth. The gateway injects the credential, so agents never see or leak it.

## Overview

Buckle 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](/docs/integrations/llms.md).

## What you will set up

* An OpenAI credential in Buckle: a pay-per-use API key or your ChatGPT plan through Codex OAuth
* Automatic injection of the `Authorization` header on requests to `api.openai.com`
* Automatic token refresh for Codex OAuth
* Per-agent access to the key, with optional organization rules

## Auth methods

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

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

**2. Add the key in Buckle**

Open the Buckle dashboard, navigate to **Settings** > **Apps** > **LLMs**, and click **Add LLM Key**. Select **OpenAI**, make sure the **API Key** tab is selected, and paste your key.

**CLI alternative:**

```bash theme={null}
buckle 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.

**1. Install Codex CLI**

```bash theme={null}
npm install -g @openai/codex
```

**2. 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`.

> [!NOTE]
>
> If you see "Please contact your workspace admin to enable device code authentication", your ChatGPT workspace admin needs to turn on device code sign-in for Codex before you can continue.

**3. Add the credentials in Buckle**

Open the Buckle dashboard, navigate to **Settings** > **Apps** > **LLMs**, and click **Add LLM key**. Select **OpenAI** and switch to **Codex (OAuth)** under **How to connect**. The dialog shows the two steps: run `codex login --device-auth` (click the command to copy it), then upload the `auth.json` file it creates (`~/.codex/auth.json`).

![The OpenAI key window in Buckle with Codex (OAuth) selected, showing the login command and the auth.json upload](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/openai-codex-oauth.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=7a1983ce76ee3ce1dfd59aec22d0e33a)

Once connected, an agent's model list shows the models your ChatGPT login can use. Some API-only models are not available through a ChatGPT login.

**CLI alternative:**

```bash theme={null}
buckle 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.

## How it works

1. Your credentials are encrypted and stored by Buckle (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

Access is per agent: [attach](/docs/guides/agent-access.md) the key to each agent that needs it — an agent without the grant can't use it at all. Organization [rules](/docs/guides/rules.md) add guardrails on top: rate-limit requests, restrict agents to specific models by blocking certain paths, or flag high-cost operations for manual approval. Everything is checked before credential injection, so a blocked request never reaches OpenAI.

## FAQ

> [accordion] How do I rotate my OpenAI API key?
>
> Create a new key at [platform.openai.com/api-keys](https://platform.openai.com/api-keys), then update it in the Buckle dashboard. All agents pick up the new key automatically, with no changes to agent config. Revoke the old key in OpenAI afterward.

> [accordion] How do I keep my OpenAI key out of the agent's context?
>
> Store it in Buckle instead of an environment variable or prompt. The gateway adds the `Authorization` header at the proxy, so the agent never holds the raw key and can't print, log, or commit it. See [How it works](/docs/how-it-works.md).

> [accordion] Can I use my ChatGPT Plus or Pro plan instead of API billing?
>
> Yes. Use the [Codex (OAuth)](#setup-codex-oauth) method: run `codex login --device-auth` and upload `~/.codex/auth.json`. Requests then count against your ChatGPT subscription.

> [accordion] Do I need to re-authenticate when the Codex token expires?
>
> No. The gateway uses the stored refresh token to get a new access token and saves it, so agents aren't interrupted. If you sign in to Codex again, upload the new `auth.json` and agents use it automatically.

> [accordion] Can I limit which models or how many requests an agent sends?
>
> Yes. [Attach](/docs/guides/agent-access.md) the key only to agents that need it, then add [rules](/docs/guides/rules.md) to rate-limit requests, block certain paths, or require approval for high-cost calls.


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