Documentation 2026-10-26 23:58 UTC to 2026-10-27 23:58 UTC

208 icon: "storage",208 icon: "storage",

209 },209 },

210 {210 {

211 title: "Sign in with ChatGPT through a gateway",211 title: "Connect to a gateway",

212 description:212 description:

213 "Keep your gateway for model requests while using your ChatGPT workspace identity.",213 "Connect to your organization's model gateway with or without ChatGPT sign-in.",

214 href: "/codex/enterprise/sign-in-with-chatgpt-through-a-gateway",

215 icon: "connect",

216 },

217 {

218 title: "Use API/provider credentials",

219 description:

220 "Configure one Codex client to use your organization's model gateway and verify the connection.",

221 href: "/codex/enterprise/connect-to-a-gateway",214 href: "/codex/enterprise/connect-to-a-gateway",

222 icon: "connect",215 icon: "connect",

223 },216 },

7Bedrock using AWS-managed authentication and access controls.7Bedrock using AWS-managed authentication and access controls.

8 8 

9This page covers direct access to Bedrock. If your organization already9This page covers direct access to Bedrock. If your organization already

10 provides a model gateway, follow [Use API/provider10 provides a model gateway, follow [Connect to a gateway without ChatGPT

11 credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway). To configure a gateway11 sign-in](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway). That path supports native

12 backed by Bedrock, see [Bedrock through12 gateway OAuth with your organization's identity provider; the gateway manages

13 LiteLLM](https://learn.chatgpt.com/docs/enterprise/bedrock-through-litellm).13 the Bedrock credentials. To configure a gateway backed by Bedrock, see

14 [Bedrock through LiteLLM](https://learn.chatgpt.com/docs/enterprise/bedrock-through-litellm).

14 15 

15## How it works16## How it works

16 17 

2 2 

3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4 

5For a local client using an organization-provided model gateway, choose5To connect a local client to your organization's gateway with or without ChatGPT sign-in, see [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway).

6[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/sign-in-with-chatgpt-through-a-gateway)

7or [API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway).

8Direct Bedrock access uses the6Direct Bedrock access uses the

9[Amazon Bedrock authentication options](https://learn.chatgpt.com/docs/amazon-bedrock#authentication-options).7[Amazon Bedrock authentication options](https://learn.chatgpt.com/docs/amazon-bedrock#authentication-options).

10 8 

401 399 

402- **OpenAI authentication**: Set `requires_openai_auth = true` to use OpenAI authentication. You can then sign in with ChatGPT or an API key. This is useful when you access OpenAI models through an LLM proxy server. When `requires_openai_auth = true`, Codex ignores `env_key`.400- **OpenAI authentication**: Set `requires_openai_auth = true` to use OpenAI authentication. You can then sign in with ChatGPT or an API key. This is useful when you access OpenAI models through an LLM proxy server. When `requires_openai_auth = true`, Codex ignores `env_key`.

403- **Environment variable authentication**: Set `env_key = "<ENV_VARIABLE_NAME>"` to use a provider-specific API key from the local environment variable named `<ENV_VARIABLE_NAME>`.401- **Environment variable authentication**: Set `env_key = "<ENV_VARIABLE_NAME>"` to use a provider-specific API key from the local environment variable named `<ENV_VARIABLE_NAME>`.

404- **No authentication**: If you don't set `requires_openai_auth` (or set it to `false`) and you don't set `env_key`, Codex assumes the provider doesn't require authentication. This is useful for local models.402- **Native gateway OAuth**: Configure `[model_providers.<id>.gateway_oauth]` for browser sign-in through your organization's identity provider. It works with or without ChatGPT sign-in. See [Native gateway OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#use-native-gateway-oauth) for the gateway requirements and configuration.

403- **Command-backed authentication**: Configure `[model_providers.<id>.auth]` to obtain a token from an installed [credential helper](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers).

404- **No authentication**: For a local model that doesn't require credentials, leave `requires_openai_auth` unset or `false` and omit credential settings, including `env_key`, `experimental_bearer_token`, `auth`, and `gateway_oauth`.

405 405 

406</ContentModeSwitch>406</ContentModeSwitch>

180## Custom model providers180## Custom model providers

181 181 

182If your organization provides a model gateway, follow182If your organization provides a model gateway, follow

183[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/sign-in-with-chatgpt-through-a-gateway)183[Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)

184or [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)

185for client setup and verification. For organization-wide deployment, see184for client setup and verification. For organization-wide deployment, see

186[Roll out a gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway).185[Roll out a gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway).

187 186 

232env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }231env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

233```232```

234 233 

234For browser sign-in through your organization's identity provider, use

235[native gateway OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#use-native-gateway-oauth).

236Configure `[model_providers.<id>.gateway_oauth]` with the authorization and token

237URLs, public client ID, and token delivery settings. This works with

238`requires_openai_auth = false`; ChatGPT sign-in, PowerShell, the Azure CLI, and

239an external credential helper aren't required. The gateway must accept the OAuth

240token in the configured cookie or custom header.

241 

235Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:242Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:

236 243 

237```toml244```toml

180## Custom model providers180## Custom model providers

181 181 

182If your organization provides a model gateway, follow182If your organization provides a model gateway, follow

183[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/sign-in-with-chatgpt-through-a-gateway)183[Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)

184or [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)

185for client setup and verification. For organization-wide deployment, see184for client setup and verification. For organization-wide deployment, see

186[Roll out a gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway).185[Roll out a gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway).

187 186 

232env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }231env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

233```232```

234 233 

234For browser sign-in through your organization's identity provider, use

235[native gateway OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#use-native-gateway-oauth).

236Configure `[model_providers.<id>.gateway_oauth]` with the authorization and token

237URLs, public client ID, and token delivery settings. This works with

238`requires_openai_auth = false`; ChatGPT sign-in, PowerShell, the Azure CLI, and

239an external credential helper aren't required. The gateway must accept the OAuth

240token in the configured cookie or custom header.

241 

235Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:242Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:

236 243 

237```toml244```toml

12 see [Amazon Bedrock](https://learn.chatgpt.com/docs/amazon-bedrock).12 see [Amazon Bedrock](https://learn.chatgpt.com/docs/amazon-bedrock).

13 13 

14Other gateway products follow the same [gateway requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility)14Other gateway products follow the same [gateway requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility)

15and [API/provider connection flow](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway).15and [gateway connection flow](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway).

16 16 

17## Connect to an existing gateway17## Connect to an existing gateway

18 18 

21- The HTTPS base URL, such as `https://gateway.example.com/v1`.21- The HTTPS base URL, such as `https://gateway.example.com/v1`.

22- The model alias that LiteLLM routes to an approved Bedrock model.22- The model alias that LiteLLM routes to an approved Bedrock model.

23- The provider ID to use in Codex configuration.23- The provider ID to use in Codex configuration.

24- A scoped gateway credential or an authentication helper that returns it.24- Native gateway OAuth settings, a scoped gateway API key, or an authentication

25 helper that returns the key.

25- Any model catalog distributed with your organization's configuration.26- Any model catalog distributed with your organization's configuration.

26 27 

27Then complete the connection in this order:28Then complete the connection in this order:

291. Ask your gateway team to confirm that the gateway serves `POST /v1/responses`,301. Ask your gateway team to confirm that the gateway serves `POST /v1/responses`,

30 streams responses, preserves follow-up turns and tool calls, and routes the31 streams responses, preserves follow-up turns and tool calls, and routes the

31 approved alias. See [Gateway compatibility](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility).32 approved alias. See [Gateway compatibility](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility).

322. Follow [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider)332. Follow [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider)

33 to configure the provider, model, and credential.34 to configure the provider, model, and credential.

343. Verify the active provider and alias, send the short `gateway-ok` prompt from353. Verify the active provider and alias, send the short `gateway-ok` prompt from

35 the connection guide, and confirm that the LiteLLM record shows the expected36 the connection guide, and confirm that the LiteLLM record shows the expected

38 39 

39Your gateway credential authenticates you to LiteLLM. The gateway manages its own Bedrock credentials; you don't need to copy those credentials to your workstation.40Your gateway credential authenticates you to LiteLLM. The gateway manages its own Bedrock credentials; you don't need to copy those credentials to your workstation.

40 41 

42If your gateway accepts OAuth access tokens, use [native gateway

43OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#use-native-gateway-oauth) for browser

44sign-in without ChatGPT sign-in or a credential helper. Confirm that your deployed

45gateway validates the token in the configured cookie or custom header. A LiteLLM

46API key alone doesn't enable this flow.

47 

41## Prepare a gateway48## Prepare a gateway

42 49 

43Use this section only when you need to create a LiteLLM gateway before connecting50Use this section only when you need to create a LiteLLM gateway before connecting

157Complete these checks before expanding access:164Complete these checks before expanding access:

158 165 

1591. Confirm that the HTTPS certificate matches the gateway host name and the service is healthy.1661. Confirm that the HTTPS certificate matches the gateway host name and the service is healthy.

1602. Connect one user through [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway).1672. Connect one user through [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway).

1613. Run a short prompt, a follow-up turn, and a read-only tool task.1683. Run a short prompt, a follow-up turn, and a read-only tool task.

1624. Confirm that gateway records show the expected identity, alias, and upstream route without exposing credentials or sensitive prompt content.1694. Confirm that gateway records show the expected identity, alias, and upstream route without exposing credentials or sensitive prompt content.

1635. Test credential expiration or revocation and confirm that unauthorized model aliases are rejected.1705. Test credential expiration or revocation and confirm that unauthorized model aliases are rejected.

1# Use API/provider credentials through a gateway1# Connect to a gateway

2 2 

3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4 

5Connect Codex to an LLM gateway using the gateway URL, model alias, and credential5Connect Codex to your organization's model gateway using the provider settings and authentication method your gateway team supplies. The gateway routes model requests to your backend, such as Amazon Bedrock.

6or token resolver your organization provides.

7 

8To keep the gateway while signing in with a ChatGPT workspace, use

9[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/sign-in-with-chatgpt-through-a-gateway).

10 6 

11For an organization-wide rollout, see [Roll out a7For an organization-wide rollout, see [Roll out a

12 gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway). For the required API behavior,8 gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway). For the required API behavior,

35 31 

36- The HTTPS gateway base URL, including its API path, such as `https://gateway.example.com/v1`.32- The HTTPS gateway base URL, including its API path, such as `https://gateway.example.com/v1`.

37- The model name and provider ID to use.33- The model name and provider ID to use.

38- Your scoped gateway credential and its environment variable, or an installed34- The authentication method: [native gateway OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway?gateway-auth=oauth#use-native-gateway-oauth),

39 token resolver and its configuration.35 a scoped API key and its environment variable, or an installed credential helper.

36- For OAuth, the authorization URL, token URL, public client ID, required scopes,

37 and the cookie or custom header the gateway accepts.

40- Any required model catalog URL, or a catalog file and its absolute local path.38- Any required model catalog URL, or a catalog file and its absolute local path.

41 39 

40<a id="without-chatgpt-sign-in"></a>

41 

42## Configure the provider42## Configure the provider

43 43 

44Open `config.toml` at `~/.codex/config.toml` on macOS or Linux, or44Open `config.toml` at `~/.codex/config.toml` on macOS or Linux, or

63name = "Organization Gateway"63name = "Organization Gateway"

64base_url = "https://gateway.example.com/v1"64base_url = "https://gateway.example.com/v1"

65wire_api = "responses"65wire_api = "responses"

66env_key = "CODEX_GATEWAY_API_KEY"66requires_openai_auth = false

67```67```

68 68 

69If your administrator supplies a catalog URL, add it to the existing69Then add the [authentication settings](#choose-an-authentication-method) your

70gateway team supplies.

71 

72For API-key or helper authentication, if your administrator supplies a catalog

73URL, add it to the existing

70`[model_providers.enterprise-gateway]` table:74`[model_providers.enterprise-gateway]` table:

71 75 

72```toml76```toml

89add a catalog path unless the file exists at that location.93add a catalog path unless the file exists at that location.

90 94 

91`enterprise-gateway` is an illustrative provider ID. Use the same ID in95`enterprise-gateway` is an illustrative provider ID. Use the same ID in

92`model_provider`, `[model_providers.<id>]`, and `[model_providers.<id>.auth]`.96`model_provider` and its provider and authentication tables.

93This example disables web search97This example disables web search

94for the initial connection test; your administrator should verify feature support98for the initial connection test; your administrator should verify feature support

95before enabling it.99before enabling it.

96 100 

101## Choose an authentication method

102 

103Use native gateway OAuth for browser sign-in, an API key for a scoped credential, or a credential helper if your organization supplies a command.

104 

105{/* prettier-ignore */}

106<Tabs

107 id="gateway-authentication"

108 ariaLabel="Gateway authentication method"

109 param="gateway-auth"

110 defaultTab="oauth"

111 tabs={[

112 { id: "oauth", label: "Gateway OAuth" },

113 { id: "api-key", label: "API key" },

114 { id: "helper", label: "Credential helper" },

115 ]}

116>

117

118 

119 

120<a id="option-b-use-native-gateway-oauth"></a>

121 

122### Use native gateway OAuth

123 

124Gateway OAuth works independently of ChatGPT sign-in. Use it when your gateway accepts access tokens issued by your

125organization's identity provider, such as Microsoft Entra ID. Codex handles the

126browser sign-in, encrypted credential storage, and token refresh when the

127authorization server issues a refresh token.

128 

129Your gateway team must register a public OAuth client that supports the

130authorization code flow with PKCE. Add this table to the provider configuration

131in `config.toml`, replacing the URLs, client ID, and cookie name with their values:

132 

133```toml

134[model_providers.enterprise-gateway.gateway_oauth]

135authorization_url = "https://login.example.com/oauth/authorize"

136token_url = "https://login.example.com/oauth/token"

137client_id = "YOUR_PUBLIC_CLIENT_ID"

138delivery = { kind = "cookie", name = "auth-openid" }

139# redirect_port = 43127

140```

141 

142Add `scopes` and, if required, `resource` to this table using the values your

143identity provider and gateway require. Request the scopes needed for refresh

144tokens if your provider requires them. Codex uses an available loopback port by default.

145If your identity provider requires a fixed redirect URI, set `redirect_port` and

146register `http://127.0.0.1:43127/callback` for this example.

147 

148The gateway must validate the OAuth access token received in the configured

149cookie. If it accepts a custom header instead, replace `delivery` with the header

150your administrator provides, for example:

151 

152```toml

153delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }

154```

155 

156Codex reserves `Authorization`; you can't use it as the `gateway_oauth` delivery header.

157A gateway that accepts only a static API key must add support for the OAuth token

158and its delivery method before you can use this flow. The gateway continues to

159manage its own upstream credentials, such as its AWS credentials for Bedrock.

160 

161When OAuth is your only credential, keep `requires_openai_auth = false` and remove the

162previous `env_key`, `experimental_bearer_token`, or `auth` settings used for the

163gateway credential. Use a local `model_catalog_json` file if you need custom model

164metadata; OAuth alone doesn't enable remote catalog discovery.

165 

166Restart the desktop app and follow its gateway sign-in prompt to open the browser.

167In the CLI, start `codex` and follow the browser sign-in when Codex first accesses

168the gateway. Complete your organization's sign-in and MFA, then return to the

169client. If the grant expires or Codex can't refresh it, sign in again when prompted.

170 

171Native gateway OAuth requires a browser and a reachable loopback callback. It has

172no device-code fallback. If the CLI runs over SSH, set `redirect_port = 43127` in

173the OAuth table and register the matching redirect URI described above. From the

174machine with your browser, forward that port before starting Codex:

175 

176```shell

177ssh -L 43127:127.0.0.1:43127 user@remote

178```

179 

180In that SSH session, start `codex` and open the gateway sign-in URL in your local

181browser. A CLI inside a container also needs a callback reachable from the

182browser. If you can't make the callback reachable, use an API key or credential

183helper instead.

184 

185

186 

187

188 

189 

190### Use an API key

191 

192Use this setting when the gateway expects an API key in the `Authorization` header.

193 

194Add the following setting inside the existing

195`[model_providers.enterprise-gateway]` table:

196 

197```toml

198env_key = "CODEX_GATEWAY_API_KEY"

199```

200 

97Make your gateway credential available as `CODEX_GATEWAY_API_KEY` in the201Make your gateway credential available as `CODEX_GATEWAY_API_KEY` in the

98environment of the process that launches Codex, using your organization's secret202environment of the process that launches Codex, using your organization's secret

99delivery mechanism. Don't put the credential in TOML or a repository. A variable203delivery mechanism. Don't put the credential in TOML or a repository. A variable

100set in a terminal may not be available to an app launched from the desktop.204set in a terminal may not be available to an app launched from the desktop.

101 205 

206<a id="option-a-reuse-your-credential-command-with-a-helper"></a>

207 

102### Use a custom authentication header208### Use a custom authentication header

103 209 

104If your gateway requires a header such as `X-API-Key` instead of a bearer token,210If your gateway requires a header such as `X-API-Key` instead of a bearer token,

113See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for219See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for

114`model_providers.<id>.env_http_headers`.220`model_providers.<id>.env_http_headers`.

115 221 

222With ChatGPT sign-in, use the custom header for the gateway key so Codex can send the user's OpenAI credential in `Authorization`.

223 

116If the custom header is your only authentication mechanism, use224If the custom header is your only authentication mechanism, use

117`model_catalog_json`; remote catalog discovery won't run.225`model_catalog_json`; remote catalog discovery won't run.

118 226 

121If your administrator provides command-backed authentication, use their installed234If your administrator provides command-backed authentication, use their installed

122helper and configuration instead of `env_key`. Don't configure both mechanisms.235helper and configuration instead of `env_key`. Don't configure both mechanisms.

123The helper must exist on your machine; Codex doesn't install it. For example,236The helper must exist on your machine; Codex doesn't install it. For example,

124replace the example `env_key` setting with this table, using the resolver path and237add this table without `env_key`, using the resolver path and

125arguments your administrator supplies:238arguments your administrator supplies:

126 239 

127```toml240```toml

137contract. Ask your administrator how to renew your sign-in if the helper can no250contract. Ask your administrator how to renew your sign-in if the helper can no

138longer retrieve a token.251longer retrieve a token.

139 252 

253With ChatGPT sign-in, run the helper before launching Codex and pass its output through a [custom gateway header](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway?gateway-auth=api-key#use-a-custom-authentication-header) instead of configuring the `auth` table. When the key expires, get a new key and relaunch Codex.

254 

140Use resolved absolute paths for helper executables and catalog files.255Use resolved absolute paths for helper executables and catalog files.

141 256 

257

258 

259</Tabs>

260 

261<a id="why-you-would-want-this"></a>

262<a id="how-to-set-it-up"></a>

263 

264<a id="sign-in-with-chatgpt-through-a-gateway"></a>

265<a id="enable-chatgpt-sign-in-optional"></a>

266 

267## Enable ChatGPT sign-in (recommended)

268 

269If your organization uses a ChatGPT workspace, signing in gives users access to eligible features such as first-party plugins. Your workspace controls apply, and your gateway still handles model requests. [Compare feature availability](https://learn.chatgpt.com/docs/pricing#feature-availability).

270 

271Add the gateway provider to your workspace's [managed `requirements.toml`](https://learn.chatgpt.com/docs/enterprise/managed-configuration). These settings apply when users sign in to that workspace.

272 

273```toml

274# requirements.toml

275model_provider = "enterprise-gateway"

276 

277[model_providers.enterprise-gateway]

278name = "Enterprise gateway"

279base_url = "https://gateway.example.com/backend-api/codex"

280requires_openai_auth = true

281```

282 

283Configure [gateway authentication](#choose-an-authentication-method) as described above. Codex sends the user's OpenAI credential to your gateway in `Authorization`. Use a separate header for the gateway credential. With native gateway OAuth, `gateway_oauth.delivery` can specify a header or a cookie.

284 

285<a id="keep-the-credentials-on-their-own-paths"></a>

286 

287### Handle credentials at the gateway

288 

289The gateway receives two credentials on each model request. For example, when Codex sends the gateway OAuth token in a cookie:

290 

291```http

292POST /backend-api/codex/responses

293Authorization: Bearer <ChatGPT token>

294ChatGPT-Account-ID: <workspace ID, when available>

295Cookie: auth-openid=<gateway token>

296```

297 

298Validate the gateway credential and strip its cookie or custom header. Redact credentials and sensitive request data from logs. Choose which credential to use upstream:

299 

300- **Forward the user's credential for direct OpenAI inference (recommended).** This lets OpenAI attribute usage and apply inference settings for that user. For this route, the gateway must proxy `/models` and `/responses` to `https://chatgpt.com/backend-api/codex` and forward `Authorization` and any `ChatGPT-Account-ID` header unchanged.

301- **Let the gateway authenticate to the inference provider.** Use the credentials configured on the gateway for that provider. Leave the user's OpenAI token and any `ChatGPT-Account-ID` header out of the upstream request.

302 

303These diagrams show the recommended route for OpenAI inference.

304 

305<details>

306<summary>How a gateway key works with ChatGPT sign-in</summary>

307 

308 

309 

310![Reuse the credential command through a launch helper. The same gateway key moves from Authorization to X-Gateway-Key while ChatGPT sign-in supplies Authorization.](<https://developers.openai.com/images/codex/gateways/chatgpt-gateway-before-after-header-light.webp>)

311 

312 

313 

314 

315 

316![The gateway validates and removes X-Gateway-Key, then forwards ChatGPT Authorization and any account ID unchanged to the Codex backend.](<https://developers.openai.com/images/codex/gateways/chatgpt-gateway-runtime-header-light.webp>)

317 

318 

319 

320</details>

321 

322<details>

323<summary>How gateway OAuth works with ChatGPT sign-in</summary>

324 

325 

326 

327![Replace API-key gateway auth with native gateway OAuth alongside ChatGPT sign-in.](<https://developers.openai.com/images/codex/gateways/chatgpt-gateway-before-after-light.webp>)

328 

329 

330 

331 

332 

333![The gateway consumes its OAuth cookie and forwards the ChatGPT credential to the Codex backend.](<https://developers.openai.com/images/codex/gateways/chatgpt-gateway-runtime-light.webp>)

334 

335 

336 

337</details>

338 

339### Add routing headers (optional)

340 

341To route requests by configuration or tool, add headers to the same `enterprise-gateway` provider in your cloud-managed `requirements.toml`:

342 

343```toml

344[model_providers.enterprise-gateway.http_headers]

345x-portkey-config = "<gateway-routing-config-id>"

346x-portkey-metadata = '{"tool_id":"codex"}'

347```

348 

349Use `env_http_headers` for values supplied by the client environment. Send a test request and confirm that the gateway selects the intended route. See [Custom model providers](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers) for more header options.

350 

351<a id="caveats-and-limitations"></a>

352<a id="voice-through-a-gateway"></a>

353 

354Only model-provider requests use this gateway route. [Voice sessions](https://learn.chatgpt.com/docs/features/voice) use a separate route. Workspace sign-in, MCP servers, and plugins can also use other network paths.

355 

356## Start the client

357 

358With ChatGPT sign-in, start the client and sign in to the workspace that provides the managed configuration. If you use native gateway OAuth, also complete your organization's gateway sign-in when prompted. Then [verify the connection](#verify-the-connection).

359 

360For a locally configured provider, follow the instructions for your client.

361 

142### Configure the CLI362### Configure the CLI

143 363 

144The CLI reads `~/.codex/config.toml` by default on macOS or Linux. After saving364The CLI reads `~/.codex/config.toml` by default on macOS or Linux. After saving

189your administrator to confirm that the gateway recorded your user, model alias,409your administrator to confirm that the gateway recorded your user, model alias,

190and intended upstream route. Don't identify the model by asking it its name.410and intended upstream route. Don't identify the model by asking it its name.

191 411 

412If the gateway serves the model catalog, check that it returns a Codex-compatible `models` array. For OpenAI inference using the user's credential, verify that the gateway forwards the ChatGPT headers to the Codex backend.

413 

192This verifies an initial connection. Administrators should also complete the414This verifies an initial connection. Administrators should also complete the

193[rollout checks](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#test-the-client-and-gateway)415[rollout checks](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#test-the-client-and-gateway)

194for streaming, tools, and follow-up turns.416for streaming, tools, and follow-up turns.

198| Symptom | What to check |420| Symptom | What to check |

199| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |421| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

200| The expected provider isn't active. | Check the selected profile and configuration precedence. Confirm that top-level keys aren't inside a provider table. |422| The expected provider isn't active. | Check the selected profile and configuration precedence. Confirm that top-level keys aren't inside a provider table. |

201| Authentication fails. | Check that the credential variable reaches the client process, or that the installed helper can retrieve a current token. Ask the administrator to distinguish gateway authentication from upstream authentication. |423| OAuth sign-in or token delivery fails. | Check the public client registration, redirect URI, scopes, and configured cookie or header. Confirm that the gateway accepts the issued access token. |

424| API-key or helper authentication fails. | Check that the credential variable reaches the client process, or that the installed helper can retrieve a current token. Ask the administrator to distinguish gateway authentication from upstream authentication. |

202| The model isn't found. | Confirm the supplied model name and ask the administrator to check its route. |425| The model isn't found. | Confirm the supplied model name and ask the administrator to check its route. |

203| The model uses unexpected capabilities. | Ask the administrator to check that the catalog metadata matches the model behind the alias. |426| The model uses unexpected capabilities. | Ask the administrator to check that the catalog metadata matches the model behind the alias. |

204| Streaming stalls or follow-ups fail. | Ask the gateway owner to check proxy buffering, the terminal `response.completed` event, and [Gateway compatibility](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility). |427| Streaming stalls or follow-ups fail. | Ask the gateway owner to check proxy buffering, the terminal `response.completed` event, and [Gateway compatibility](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility). |

2172. Ask your gateway team to confirm that the gateway supports the4402. Ask your gateway team to confirm that the gateway supports the

218 [API behavior Codex requires](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility) and to441 [API behavior Codex requires](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility) and to

219 configure a Codex model route.442 configure a Codex model route.

2203. Obtain a scoped gateway credential or credential helper, the model name, and4433. Obtain the OAuth settings, scoped gateway credential, or credential helper,

221 any required model catalog from your gateway team.444 along with the model name and any required catalog from your gateway team.

2224. [Configure Codex](#configure-the-provider) with those values.4454. [Configure Codex](#configure-the-provider) with those values.

2235. [Verify the connection](#verify-the-connection) in the CLI or desktop app you4465. [Verify the connection](#verify-the-connection) in the CLI or desktop app you

224 plan to use. Have your gateway team complete the447 plan to use. Have your gateway team complete the

4 4 

5These requirements cover the API/provider credential path through a gateway.5These requirements cover the API/provider credential path through a gateway.

6For gateways that forward ChatGPT workspace requests, see [Sign in with6For gateways that forward ChatGPT workspace requests, see [Sign in with

7ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/sign-in-with-chatgpt-through-a-gateway).7ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#enable-chatgpt-sign-in-recommended).

8 8 

9For this path, the gateway must preserve the Responses API behavior described here:9For this path, the gateway must preserve the Responses API behavior described here:

10endpoints, streaming, continuation, tool calls, authentication, routing, and10endpoints, streaming, continuation, tool calls, authentication, routing, and

2 2 

3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4 

5Roll out the API/provider credential path through your gateway. Configure model5Roll out native gateway OAuth, API keys, or credential helpers without ChatGPT

6routes, issue developer credentials, and distribute a verified Codex6sign-in. Configure model routes, authorize users, and distribute a verified Codex

7configuration. For a gateway that forwards ChatGPT workspace requests, see7configuration. For a gateway that forwards ChatGPT workspace requests, see

8[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/sign-in-with-chatgpt-through-a-gateway).8[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#enable-chatgpt-sign-in-recommended).

9 9 

10To configure Codex on your own machine with values you were given, see [Use10To configure Codex on your own machine with values you were given, see

11 API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway). Before11 [Configure the

12 choosing or rolling out a gateway, review the [gateway compatibility12 provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider).

13 Before choosing or rolling out a gateway, review the [gateway compatibility

13 requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility).14 requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility).

14 15 

15## Prerequisites16## Prerequisites

19- A gateway serving HTTPS at the exact base URL you will distribute.20- A gateway serving HTTPS at the exact base URL you will distribute.

20- An upstream provider credential held by the gateway.21- An upstream provider credential held by the gateway.

21- Approved Codex-facing model aliases mapped to intended upstream models.22- Approved Codex-facing model aliases mapped to intended upstream models.

22- A scoped test gateway credential.23- A tested authentication method: native gateway OAuth, scoped gateway API keys,

23- A secret delivery mechanism or a tested credential helper.24 or a credential helper.

24- A way to distribute configuration, helper executables, and any catalog files.25- For OAuth, a registered public client, approved test users, and gateway support

26 for validating OAuth access tokens.

27- For API keys or helpers, a secret delivery mechanism or a tested helper.

28- A way to distribute configuration, any required helpers, and catalog files.

25 29 

26## Gateway requirements30## Gateway requirements

27 31 

44To move from a deployed gateway to a verified developer experience, complete these five checkpoints in order:48To move from a deployed gateway to a verified developer experience, complete these five checkpoints in order:

45 49 

461. [Choose model names and verify routes](#choose-model-names-and-routes).501. [Choose model names and verify routes](#choose-model-names-and-routes).

472. [Issue developer credentials](#issue-developer-credentials).512. [Choose authentication](#choose-authentication).

483. [Test Codex through the gateway](#test-the-client-and-gateway).523. [Test Codex through the gateway](#test-the-client-and-gateway).

494. [Distribute the configuration](#distribute-the-configuration).534. [Distribute the configuration](#distribute-the-configuration).

505. [Verify from a developer machine](#verify-and-operate-the-rollout).545. [Verify from a developer machine](#verify-and-operate-the-rollout).

64 68 

65Supply a model catalog when your gateway uses a model name Codex does not recognize. The catalog supplies the instructions, reasoning options, context limits, and tool capabilities Codex uses for that name. Without a matching entry, a request can reach the intended upstream model while Codex uses generic settings.69Supply a model catalog when your gateway uses a model name Codex does not recognize. The catalog supplies the instructions, reasoning options, context limits, and tool capabilities Codex uses for that name. Without a matching entry, a request can reach the intended upstream model while Codex uses generic settings.

66 70 

67Host a remote catalog with `model_providers.<id>.model_catalog_url` to update model metadata centrally, or distribute a local file with `model_catalog_json`. See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for both settings.71Host a remote catalog with `model_providers.<id>.model_catalog_url` to update model metadata centrally, or distribute a local file with `model_catalog_json`. Use a local catalog when native gateway OAuth is the only credential; OAuth alone doesn't enable remote catalog discovery. See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for both settings.

68 72 

69Get a catalog endpoint or file compatible with your Codex version from your cloud73Get a catalog endpoint or file compatible with your Codex version from your cloud

70or gateway provider. Make sure it includes each approved alias and its model74or gateway provider. Make sure it includes each approved alias and its model

94default OpenAI endpoint for the current authentication mode.98default OpenAI endpoint for the current authentication mode.

95 99 

96Discovery requires API-key, command-backed, or Codex-backend authentication.100Discovery requires API-key, command-backed, or Codex-backend authentication.

97Custom headers alone don't trigger it.101Native gateway OAuth or custom headers alone don't trigger it.

98 102 

99Coordinate catalog updates with your provider when your approved models change. Restart the client after103Coordinate catalog updates with your provider when your approved models change. Restart the client after

100changing its configuration.104changing its configuration.

125Model routing and tool authorization are separate parts of the rollout. Configure129Model routing and tool authorization are separate parts of the rollout. Configure

126MCP connections, plugin distribution, and their policies separately.130MCP connections, plugin distribution, and their policies separately.

127 131 

128## Issue developer credentials132<a id="issue-developer-credentials"></a>

133 

134## Choose authentication

135 

136### Native gateway OAuth

137 

1381. Register a public OAuth client that supports authorization code with PKCE, and

139 approve the users or groups that can sign in.

1402. Configure the gateway to validate the issued access token in the selected

141 cookie or custom header. Apply the approved models, rate limits, and budgets

142 to each user's identity.

1433. Follow [native gateway

144 OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#use-native-gateway-oauth) to collect

145 the authorization and token URLs, public client ID, scopes, optional resource,

146 token delivery settings, and any fixed redirect port. Register the matching

147 loopback redirect URI with your identity provider.

1484. Test browser sign-in, token refresh, and access revocation with a test user on

149 the CLI or desktop app you plan to deploy. Confirm that the browser can reach

150 the callback, including for remote CLI users.

151 

152Users sign in individually. You distribute OAuth configuration, not a client

153secret, gateway API key, or helper executable. Keep upstream provider credentials

154on the gateway.

155 

156### API keys or credential helpers

129 157 

1301. Issue one scoped gateway credential per developer so you can attribute usage1581. Issue one scoped gateway credential per developer so you can attribute usage

131 and revoke access individually.159 and revoke access individually.

143 171 

144## Test Codex through the gateway172## Test Codex through the gateway

145 173 

146Before distributing anything, follow [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure one isolated test user with the provider block and credential mechanism you plan to distribute.174Before distributing anything, follow [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) to configure one isolated test user with the provider block and authentication method you plan to distribute.

147 175 

148Run the checks below from the same CLI or desktop surface developers will use:176Run the checks below from the same CLI or desktop surface developers will use:

149 177 

155| Follow-up | Ask a follow-up in the same thread. | The answer uses the prior turn; the gateway accepts replayed input. If WebSocket or incremental transport is enabled, it also preserves `previous_response_id`. |183| Follow-up | Ask a follow-up in the same thread. | The answer uses the prior turn; the gateway accepts replayed input. If WebSocket or incremental transport is enabled, it also preserves `previous_response_id`. |

156| Errors and attribution | Repeat with an intentionally invalid test alias or expired test credential. | The client receives a useful routing or authentication error, and valid requests remain attributed to the test user. |184| Errors and attribution | Repeat with an intentionally invalid test alias or expired test credential. | The client receives a useful routing or authentication error, and valid requests remain attributed to the test user. |

157 185 

158After these checks succeed, direct developers to [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure and verify their own machine.186After these checks succeed, direct developers to [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) to configure and verify their own machine.

159 187 

160## Distribute the configuration188## Distribute the configuration

161 189 

162To give every machine the same connection path, distribute the gateway base URL,190To give every machine the same connection path, distribute the gateway base URL,

163provider ID, approved model alias, and credential mechanism.191provider ID, approved model alias, and authentication settings.

164 192 

165### What to distribute193### What to distribute

166 194 

167To set provider defaults, distribute this `config.toml` block through the configuration layer you chose. Use a model recognized by your Codex version, or supply the matching catalog described above. Install your token resolver at the configured command path:195For native gateway OAuth, distribute the provider and

196`[model_providers.<id>.gateway_oauth]` tables from the [connection

197guide](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#use-native-gateway-oauth), with the

198registration values collected above. Keep `requires_openai_auth = false` and omit

199`env_key`, `experimental_bearer_token`, and the command-backed `auth` table when

200OAuth is the only gateway credential.

201 

202For a credential helper, distribute the following `config.toml` block through the

203configuration layer you chose. Use a model recognized by your Codex version, or

204supply the matching catalog described above. Install your token resolver at the

205configured command path:

168 206 

169Put `model` and `model_provider` before the first TOML table. If you set207Put `model` and `model_provider` before the first TOML table. If you set

170 `model_catalog_json`, keep it there too. TOML treats keys after208 `model_catalog_json`, keep it there too. TOML treats keys after

231 269 

232### Hand developers the configuration values270### Hand developers the configuration values

233 271 

234If you do not have managed distribution, give each developer the gateway URL, provider ID, model alias, credential variable or resolver, and any catalog URL or local path. Send them to [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure and verify their own machine.272If you do not have managed distribution, give each developer the gateway URL, provider ID, model alias, OAuth configuration or credential variable or resolver, and any catalog URL or local path. Send them to [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) to configure and verify their own machine.

235 273 

236Manual setup is not an enforcement channel. Project-local `.codex/config.toml` cannot override sensitive provider or authentication routing keys.274Manual setup is not an enforcement channel. Project-local `.codex/config.toml` cannot override sensitive provider or authentication routing keys.

237 275 

242To confirm that the distributed settings reached a developer machine:280To confirm that the distributed settings reached a developer machine:

243 281 

2441. Restart Codex and confirm the expected provider and model.2821. Restart Codex and confirm the expected provider and model.

2452. Run the short test in [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#verify-the-connection).2832. Run the short test in [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#verify-the-connection).

2463. Ask one follow-up to confirm continuation, then check the gateway logs for that2843. Ask one follow-up to confirm continuation, then check the gateway logs for that

247 developer's request.285 developer's request.

248 286 

254| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |292| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

255| Expected provider is missing after restart. | Inspect the winning configuration layer. User or profile configuration can override system defaults. |293| Expected provider is missing after restart. | Inspect the winning configuration layer. User or profile configuration can override system defaults. |

256| Authentication fails for every user. | Check gateway authentication and the upstream provider credential; identify which service rejected the request. |294| Authentication fails for every user. | Check gateway authentication and the upstream provider credential; identify which service rejected the request. |

257| Authentication fails for one user. | Check that user's gateway credential or token resolver. |295| Authentication fails for one user. | Check that user's identity-provider access, gateway credential, or token resolver. |

258| Streaming stalls. | Inspect gateway buffering and terminal `response.completed` forwarding. |296| Streaming stalls. | Inspect gateway buffering and terminal `response.completed` forwarding. |

259| A model is missing or uses generic capabilities. | For a custom alias, confirm the gateway alias, Codex `model`, and catalog `slug` match. Check the [catalog](#use-a-model-catalog-for-custom-names) path and compatibility with the installed Codex version, then restart Codex. |297| A model is missing or uses generic capabilities. | For a custom alias, confirm the gateway alias, Codex `model`, and catalog `slug` match. Check the [catalog](#use-a-model-catalog-for-custom-names) path and compatibility with the installed Codex version, then restart Codex. |

260| A Windows path fails. | Use resolved absolute paths. In TOML, use single-quoted strings for Windows paths with single backslashes. |298| A Windows path fails. | Use resolved absolute paths. In TOML, use single-quoted strings for Windows paths with single backslashes. |

272| Gateway product, DNS, TLS, private networking, logging, redaction, and monitoring | Keep these services in place. Add a Codex-facing route that satisfies the [Gateway compatibility requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility). |310| Gateway product, DNS, TLS, private networking, logging, redaction, and monitoring | Keep these services in place. Add a Codex-facing route that satisfies the [Gateway compatibility requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility). |

273| Bedrock account, provider credential, IAM boundary, inference profiles, and credential rotation | Keep them only when they authorize the upstream models behind the new Codex aliases. The provider credential remains on the gateway. |311| Bedrock account, provider credential, IAM boundary, inference profiles, and credential rotation | Keep them only when they authorize the upstream models behind the new Codex aliases. The provider credential remains on the gateway. |

274| Claude `/v1/messages` route, Bedrock InvokeModel shape, Anthropic headers, and Claude-specific retries or errors | Do not reuse these as proof of compatibility. Codex needs `POST /v1/responses`, Responses streaming, continuation, tool calls, and useful errors. |312| Claude `/v1/messages` route, Bedrock InvokeModel shape, Anthropic headers, and Claude-specific retries or errors | Do not reuse these as proof of compatibility. Codex needs `POST /v1/responses`, Responses streaming, continuation, tool calls, and useful errors. |

275| `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, or `apiKeyHelper` | Codex does not support `apiKeyHelper`. Issue a scoped Codex gateway credential and configure it with `env_key` or a Codex command-backed token resolver. |313| `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, or `apiKeyHelper` | Codex does not support `apiKeyHelper`. Configure native gateway OAuth, a scoped key with `env_key`, or a Codex command-backed token resolver. |

276| Claude model names, `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_*_MODEL`, `modelOverrides`, and Bedrock profile mappings | Have your gateway team [choose model names and configure any custom aliases](#choose-model-names-and-routes). Use the model name and any [model catalog JSON](https://learn.chatgpt.com/docs/config-file/config-reference) they provide. |314| Claude model names, `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_*_MODEL`, `modelOverrides`, and Bedrock profile mappings | Have your gateway team [choose model names and configure any custom aliases](#choose-model-names-and-routes). Use the model name and any [model catalog JSON](https://learn.chatgpt.com/docs/config-file/config-reference) they provide. |

277| Claude `settings.json`, `managed-settings.json`, JSON `env` blocks, `plist`, or registry payloads | Keep the same MDM or configuration-management channel, but distribute Codex `config.toml` and supported `requirements.toml` values instead. |315| Claude `settings.json`, `managed-settings.json`, JSON `env` blocks, `plist`, or registry payloads | Keep the same MDM or configuration-management channel, but distribute Codex `config.toml` and supported `requirements.toml` values instead. |

278 316 

280 318 

2811. Inventory the current Claude path: gateway URL, credential source, required headers, model aliases, Bedrock profile mappings, and managed delivery channel.3191. Inventory the current Claude path: gateway URL, credential source, required headers, model aliases, Bedrock profile mappings, and managed delivery channel.

2822. Add a parallel Codex-facing Responses route and Codex model aliases.3202. Add a parallel Codex-facing Responses route and Codex model aliases.

2833. Issue one scoped Codex credential. If Codex will use a static credential, expose that new credential through `env_key`; if Claude uses a credential helper, implement and test the Codex command-backed resolver contract.3213. Choose [native gateway OAuth, an API key, or a credential helper](#choose-authentication) and authorize one test user. For a static credential, expose it through `env_key`; for a helper, implement and test the Codex command-backed resolver contract.

2844. Configure that developer with the [provider block](#what-to-distribute). For a managed rollout, translate the payload into the Codex paths and precedence described in [Roll out a gateway](#distribute-the-configuration).3224. Configure that developer with the [provider block](#what-to-distribute). For a managed rollout, translate the payload into the Codex paths and precedence described in [Roll out a gateway](#distribute-the-configuration).

2855. Run the short connection check on the developer's actual CLI or desktop surface, then run the full streaming, continuation, tool-call, error, logging, and alias-routing checks in [Test Codex through the gateway](#test-the-client-and-gateway).3235. Run the short connection check on the developer's actual CLI or desktop surface, then run the full streaming, continuation, tool-call, error, logging, and alias-routing checks in [Test Codex through the gateway](#test-the-client-and-gateway).

2866. After the pilot passes, [distribute the configuration](#distribute-the-configuration) to the remaining developers.3246. After the pilot passes, [distribute the configuration](#distribute-the-configuration) to the remaining developers.

287 325 

288## Related docs326## Related docs

289 327 

290- [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)328- [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider)

291- [MCP](https://learn.chatgpt.com/docs/extend/mcp)329- [MCP](https://learn.chatgpt.com/docs/extend/mcp)

292- [Plugins](https://learn.chatgpt.com/docs/plugins)330- [Plugins](https://learn.chatgpt.com/docs/plugins)

293- [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration)331- [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration)

428 428 

4291. Create separate environments for different trust levels, such as no-internet-review, approved-dependencies-build, and cyber-lab.4291. Create separate environments for different trust levels, such as no-internet-review, approved-dependencies-build, and cyber-lab.

430 430 

4312. In the environment configuration, leave **Allow Codex to access internet** off unless the workflow needs internet access.4312. In the environment configuration, turn off **Enable all public internet access** and **Enable package manager domains**.

432 432 

4333. When access is required, turn on **Allow Codex to access internet**. Under **Allow domains**, choose **Custom domains only**, then add exact required hosts under **Additional allowed domains**.4333. When public internet access is required, add exact approved hosts under **Additional allowed domains**. Remove **HTTP secrets** that allow unapproved public destinations. To block public internet access outside the VPN, leave that list empty and remove **HTTP secrets** that allow public destinations.

434 434 

4354. Save and test the services during setup. Publish or republish the environment, then test access to approved and unapproved destinations in a new task. Review setup scripts separately: pin dependencies, prefer approved mirrors, and avoid executable downloads that have not been reviewed.4354. Save and test the services during setup. Publish or republish the environment, then test access to approved and unapproved destinations in a new task. Review setup scripts separately: pin dependencies, prefer approved mirrors, and avoid executable downloads that have not been reviewed.

436 436 

589```589```

590 590 

5915. Choose the credential flow for your Cloud environment:5915. Choose the credential flow for your Cloud environment:

592 - In current Codex Cloud, use **Network secrets** for credentials sent to an allowed HTTPS service. Programs receive a placeholder, and the proxy substitutes the real value for approved destinations on port 443 during setup and tasks. The raw credential is not placed in a local process or file. Direct environment variables are available to programs. See [Environment variables and network secrets](https://learn.chatgpt.com/docs/environments/cloud-environments#configure-environment-variables-and-network-secrets).592 - In current Codex Cloud, use **HTTP secrets** for credentials sent to an allowed HTTPS service. Programs receive a placeholder, and the proxy substitutes the real value for approved destinations on port 443 during setup and tasks. The raw credential is not placed in a local process or file. Direct environment variables are available to programs. See [Environment variables and network secrets](https://learn.chatgpt.com/docs/environments/cloud-environments#configure-environment-variables-and-network-secrets).

593 - In Codex Cloud (Legacy), secrets support setup-time authentication and are removed before the agent phase; environment variables remain for the full chat. See [Legacy Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environment).593 - In Codex Cloud (Legacy), secrets support setup-time authentication and are removed before the agent phase; environment variables remain for the full chat. See [Legacy Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environment).

594 594 

5956. If the agent needs authentication, use an independent broker to provide short-lived credentials scoped to the exact target and action. See [Recommended configuration](https://learn.chatgpt.com/docs/cyber-safety/recommended-configuration).5956. If the agent needs authentication, use an independent broker to provide short-lived credentials scoped to the exact target and action. See [Recommended configuration](https://learn.chatgpt.com/docs/cyber-safety/recommended-configuration).

990 990 

991#### Configure cloud environment networking separately991#### Configure cloud environment networking separately

992 992 

993In the current Codex Cloud interface, open the environment configuration. Leave **Allow Codex to access internet** off. If you need internet access, turn it on and choose **Custom domains only**, add the exact required hosts under **Additional allowed domains**, then save the configuration, publish or republish the environment, and test a new task.993In the current Codex Cloud interface, open the environment configuration. Turn off **Enable all public internet access** and **Enable package manager domains**. If public internet access is required, add exact approved hosts under **Additional allowed domains**. Remove **HTTP secrets** that allow unapproved public destinations. To block public internet access outside the VPN, leave that list empty and remove **HTTP secrets** that allow public destinations. Save the configuration, publish or republish the environment, and test a new task.

994 994 

995Review service authentication and capabilities independently.995Review service authentication and capabilities independently.

996 996 

124 124 

125Codex identifies missing configuration and asks for values it can't infer.125Codex identifies missing configuration and asks for values it can't infer.

126In the environment configuration, select **Manage** beside **Environment variables**126In the environment configuration, select **Manage** beside **Environment variables**

127or **Network secrets**. Choose how to supply each value:127or **HTTP secrets**. Choose how to supply each value:

128 128 

129| Configuration | Use it for | Delivery |129| Configuration | Use it for | Delivery |

130| -------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |130| -------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |

210## Agent Security210## Agent Security

211 211 

212The environment's [internet-access settings](#connect-to-services) define which212The environment's [internet-access settings](#connect-to-services) define which

213domains its VM can reach. VPN settings connect that VM to services on a private213public internet destinations its VM can reach. VPN settings independently connect

214network.214that VM to services on a private network.

215 215 

216In Enterprise workspaces, admins use216In Enterprise workspaces, admins use

217[Agent Security](https://learn.chatgpt.com/docs/enterprise/agent-security) to configure workspace217[Agent Security](https://learn.chatgpt.com/docs/enterprise/agent-security) to configure workspace

227Configure access to the package registries, APIs, and other services your227Configure access to the package registries, APIs, and other services your

228workflow needs:228workflow needs:

229 229 

2301. In the environment configuration, turn on **Allow Codex to access internet**.2301. In the environment configuration, choose how much public internet access your

2312. Under **Allow domains**, choose **Package managers** or **Custom domains only**,231 workflow needs. Turn on **Enable all public internet access** for full public access.

232 then add required hosts under **Additional allowed domains**. Use232 This includes the destinations covered by the package-manager and

233 **All (unrestricted)** when the workflow needs broader access.233 additional-domain controls, so those narrower controls are disabled.

2342. To restrict public internet access, turn off **Enable all public internet access**, then allow

235 package managers or add specific hosts under **Additional allowed domains**.

236 Turning off full public access still permits these allowed destinations.

2343. Save and test the services during setup. Publish or republish, then verify2373. Save and test the services during setup. Publish or republish, then verify

235 access in a new task.238 access in a new task.

236 239 

240Public internet access and [VPN access](#private-networking-vpn) are independent.

241You can use either or both. Public internet settings apply to connections outside

242Tailscale, even when a Tailscale subnet route uses public IP addresses. Restricting

243public internet access doesn't disable the configured VPN.

244 

237For workspace requirements, see [Agent Security](#agent-security). Allowing a245For workspace requirements, see [Agent Security](#agent-security). Allowing a

238destination doesn't supply credentials or grant permissions in that service.246destination doesn't supply credentials or grant permissions in that service.

239 247 

276 284 

277## Private networking (VPN)285## Private networking (VPN)

278 286 

279Give cloud tasks access to internal APIs, package registries, and other HTTP or287Give cloud tasks access to services on your private network through a VPN

280HTTPS services on your private network through a VPN connection.288connection. Tailscale uses your configured private DNS, subnet routes, and access

289rules. You don't need a separate Codex IP or domain allowlist for destinations

290reached through Tailscale, including HTTP, HTTPS, and other TCP services.

281 291 

2821. Open the environment's **Advanced** > **VPN** settings and select **Add**.2921. In the environment configuration, select the pencil icon beside **Tailscale**.

2832. Enter the connection credentials from your VPN provider.2932. Enter the connection credentials from your VPN provider.

2843. Allow the required destinations in both your VPN's access rules and the2943. Configure the required routes, DNS, and access rules in Tailscale so the

285 environment's [internet-access settings](#connect-to-services).295 environment's VPN identity can reach the intended services.

2864. Save, then publish or republish. Start a new task and test the service.2964. Save, then publish or republish. Start a new task and test the service.

287 297 

288Tailscale is currently the supported VPN provider. When creating a Tailscale298Tailscale is currently the supported VPN provider. When creating a Tailscale

297the Tailscale admin console to send queries for your internal domain to your DNS307the Tailscale admin console to send queries for your internal domain to your DNS

298server. Use the service's fully qualified hostname, such as308server. Use the service's fully qualified hostname, such as

299`api.corp.example.com`, which must resolve to an IPv4 address. The destination309`api.corp.example.com`, which must resolve to an IPv4 address. The destination

300must also be allowed by the environment's internet-access settings and your310must be reachable through your configured Tailscale routes and permitted by

301Tailscale access rules.311your Tailscale access rules.

302 312 

303Tasks in a shared environment use its configured VPN identity.313Tasks in a shared environment use its configured VPN identity.

304 314 

315### Connect to TCP services

316 

317Use the VPN to connect to TCP services such as databases or SSH. TCP destinations

318must use IPv4 addresses routed through Tailscale. For hostnames, every resolved

319IPv4 address must use those routes. Platform-protected addresses remain blocked.

320 

321TCP clients must connect through the environment's HTTP CONNECT proxy at

322`proxy:8088`, either directly or through a local forwarding tool. For hostname

323destinations, preserve the hostname for proxy-side DNS resolution. TCP tunnels

324don't intercept TLS or inject network secrets: the client must supply the service's

325credentials and verify its TLS certificate when applicable. Requests that need

326[network-secret substitution](#configure-environment-variables-and-network-secrets)

327must use the configured HTTPS proxy and meet the secret's allowed-domain rules;

328substitution works on port 443.

329 

330After changing VPN configuration, save the changes, then publish or republish the

331environment. Replace existing running environments to use the updated VPN

332configuration. Start a new task and test access. Detaching the VPN from a draft

333doesn't revoke existing connections; replace or terminate the affected environment

334to revoke access.

335 

305<a id="connect-a-cloud-identity"></a>336<a id="connect-a-cloud-identity"></a>

306<a id="configure-an-aws-role-connection"></a>337<a id="configure-an-aws-role-connection"></a>

307<a id="attach-an-azure-connection"></a>338<a id="attach-an-azure-connection"></a>

490 521 

491- **Environment variables:** use these for values that programs need to read522- **Environment variables:** use these for values that programs need to read

492 directly, such as `APP_MODE=development`.523 directly, such as `APP_MODE=development`.

493- **Network secrets:** use these for credentials sent to an allowed HTTPS524- **HTTP secrets:** use these for credentials sent to an allowed HTTPS

494 service, such as a private registry token. Programs receive a placeholder;525 service, such as a private registry token. Programs receive a placeholder;

495 the proxy substitutes the credential in matching requests. If the program526 the proxy substitutes the credential in matching requests. If the program

496 needs to read the raw value, add it under **Environment variables**.527 needs to read the raw value, add it under **Environment variables**.

506 537 

5071. Confirm the client uses the environment's configured HTTP/HTTPS proxy.5381. Confirm the client uses the environment's configured HTTP/HTTPS proxy.

508 When testing with `curl`, omit `--noproxy` so the request uses that proxy.539 When testing with `curl`, omit `--noproxy` so the request uses that proxy.

5092. Check the destination against both the environment's allowed domains and5402. For Tailscale destinations, check the VPN's routes and access rules. For

510 the VPN's access rules.541 public internet destinations, check the environment's allowed domains.

5113. If the service is reachable by IP address but not by hostname, check your5423. If the service is reachable by IP address but not by hostname, check your

512 Tailscale DNS settings. For an internal company domain, verify that split DNS543 Tailscale DNS settings. For an internal company domain, verify that split DNS

513 points to the correct DNS server and that the server is reachable through544 points to the correct DNS server and that the server is reachable through

43 43 

44- [Fix a finding from your security scan](https://developers.openai.com/codex/use-cases/fix-a-finding-from-your-security-scan): Use the Codex Security plugin to turn a reviewed scan finding into a focused patch44- [Fix a finding from your security scan](https://developers.openai.com/codex/use-cases/fix-a-finding-from-your-security-scan): Use the Codex Security plugin to turn a reviewed scan finding into a focused patch

45- [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog): Bring in approved findings from ticketing tools or vulnerability reporting systems, then use...45- [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog): Bring in approved findings from ticketing tools or vulnerability reporting systems, then use...

46 

47## Secure the SDLC

48 

49Automate security reviews by defining your application’s security requirements, giving Codex the context to assess changes, and configuring reviews for pull requests and dependency updates.

50 

51- [Set up security context](https://developers.openai.com/codex/use-cases/set-up-security-context): Learn how to prepare and configure the context Codex needs for security reviews and scans.

52- [Automate security reviews in GitHub Cloud](https://developers.openai.com/codex/use-cases/automate-security-reviews-in-github-cloud): Connect a repository and configure review triggers with Codex Security Review.

53- [Review code changes in Codex Desktop](https://developers.openai.com/codex/use-cases/review-code-changes-in-codex-desktop): Start a security review from Codex or your repository’s Codex project.

54- [Run security reviews from the CLI](https://developers.openai.com/codex/use-cases/run-security-reviews-from-the-cli): Use Codex Security CLI to review uncommitted work or changes on a branch.

55- [Create custom review workflows with GitHub Actions](https://developers.openai.com/codex/use-cases/create-custom-review-workflows-with-github-actions): Make security reviews a repeatable part of your development process

56- [Manage supply chain risk in the CI/CD](https://developers.openai.com/codex/use-cases/manage-supply-chain-risk-in-cicd): Assess how third-party dependencies affect your application’s security with Codex Security CLI

1---

2name: Automate security reviews in GitHub Cloud

3tagline: Check proposed changes for security risks before they merge.

4summary: Connect a repository and configure review triggers with Codex Security Review.

5bestFor:

6 - Developers who want security feedback within their existing GitHub

7 pull-request workflow.

8 - Application security teams establishing consistent reviews of proposed code

9 changes.

10 - Repository maintainers tailoring reporting thresholds for sensitive areas

11 such as authentication, authorization, and payments.

12relatedLinks:

13 - label: Configure automatic security reviews

14 url: /codex/security/security-review#configure-security-review

15 - label: Set reporting thresholds and path overrides

16 url: /codex/security/security-review#set-reporting-thresholds

17 - label: Review GitHub pull requests with Codex

18 url: /codex/third-party/github

19---

20 

21> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

22 

23The fastest way to automate security reviews in GitHub Cloud is through the [Security Review](https://developers.openai.com/codex/security/security-review) feature within ChatGPT. This is available through the same product surface as Codex Code Reviews available within your organization at [https://chatgpt.com/codex/cloud/settings/code-review](https://chatgpt.com/codex/cloud/settings/code-review).

24 

25Codex Security Review goes deeper than Code Review on security-specific risks by analyzing the pull request diff, supporting repository context, and configured threat models or security guidance.

26 

27## Difference between Code Review and Security Review

28 

29Code Review is a broad engineering review that assesses code quality. For example, Code Review asks: “Could this change break the product or introduce a serious engineering problem?” It reviews issues such as incorrect control flow, data corruption or loss, compatibility regressions, or incorrect API behavior. The intended users for Code Review are software developers within the organization.

30 

31Codex Security is a specialized, deeper assessment of security risks in the same PR changes. Security Review is for both software developers responsible for remediating vulnerabilities, as well as application security engineers responsible for securing CI/CD pipelines and source code. It assesses issues such as authentication and authorization bypasses, cross-tenant access, injection and unsafe parsing, or sensitive data exposure.

32 

33## Configure security reviews

34 

35 

36There are two options for configuring security reviews. The auto-review reporting determines which findings Codex posts to the PR when Security Review runs automatically. It is defaulted to High, so only High and Critical findings are posted.

37 

38The option for manual review controls which findings Codex posts after someone explicitly requests a Security Review. It is defaulted to Medium, so Medium, High, and Critical findings are posted.

39 

40When configured, posted vulnerabilities will surface within the PR.

41 

42![Security finding posted on a GitHub pull request.](https://developers.openai.com/images/codex/secure-sdlc/github-review-finding.webp)

43 

44It’s best to choose automatic reporting thresholds around what the team is prepared to investigate consistently. For a targeted investigation, use the manual review settings to surface the additional detail relevant to that question.

45 

46## Set path overrides

47 

48 

49Path-based reporting overrides the minimum severity published to the Github PR. Given that a repository’s risk is rarely uniform, this feature can tailor the risk threshold for more critical path, such as:

50 

51- Lowering the threshold for authentication, authorization, payments, cryptography, CI workflows, of infrastructure.

52 

53- Keeping a higher threshold for lower-risk or especially noisy areas.

54 

55You can modify the path overrides within the Codex Cloud settings for the selected repo. In this example below, we have established that `src/**` should have auto reviews for low vulnerabilities or higher. Changes to GitHub workflows or dependencies will enforce reporting for medium vulnerabilities.

56 

57![Path overrides for source files, workflows, and dependencies.](https://developers.openai.com/images/codex/secure-sdlc/path-overrides.webp)

43 43 

44- [Fix a finding from your security scan](https://developers.openai.com/codex/use-cases/fix-a-finding-from-your-security-scan): Use the Codex Security plugin to turn a reviewed scan finding into a focused patch44- [Fix a finding from your security scan](https://developers.openai.com/codex/use-cases/fix-a-finding-from-your-security-scan): Use the Codex Security plugin to turn a reviewed scan finding into a focused patch

45- [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog): Bring in approved findings from ticketing tools or vulnerability reporting systems, then use...45- [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog): Bring in approved findings from ticketing tools or vulnerability reporting systems, then use...

46 

47## Secure the SDLC

48 

49Automate security reviews by defining your application’s security requirements, giving Codex the context to assess changes, and configuring reviews for pull requests and dependency updates.

50 

51- [Set up security context](https://developers.openai.com/codex/use-cases/set-up-security-context): Learn how to prepare and configure the context Codex needs for security reviews and scans.

52- [Automate security reviews in GitHub Cloud](https://developers.openai.com/codex/use-cases/automate-security-reviews-in-github-cloud): Connect a repository and configure review triggers with Codex Security Review.

53- [Review code changes in Codex Desktop](https://developers.openai.com/codex/use-cases/review-code-changes-in-codex-desktop): Start a security review from Codex or your repository’s Codex project.

54- [Run security reviews from the CLI](https://developers.openai.com/codex/use-cases/run-security-reviews-from-the-cli): Use Codex Security CLI to review uncommitted work or changes on a branch.

55- [Create custom review workflows with GitHub Actions](https://developers.openai.com/codex/use-cases/create-custom-review-workflows-with-github-actions): Make security reviews a repeatable part of your development process

56- [Manage supply chain risk in the CI/CD](https://developers.openai.com/codex/use-cases/manage-supply-chain-risk-in-cicd): Assess how third-party dependencies affect your application’s security with Codex Security CLI

1---

2name: Create custom review workflows with GitHub Actions

3tagline: Run security checks on your own triggers and keep the results for review.

4summary: Make security reviews a repeatable part of your development process.

5 Configure a GitHub Actions workflow that runs Codex Security on proposed

6 changes and saves the results for your team to inspect.

7bestFor:

8 - Platform and application security teams adding security checks to GitHub

9 Actions.

10 - Repository maintainers configuring custom review triggers and scan scope.

11 - Teams that need repeatable reviews with saved findings, evidence, and

12 coverage reports.

13relatedLinks:

14 - label: Run Codex Security in GitHub Actions

15 url: /codex/security/cli/ci/github

16 - label: Save reports and upload SARIF results

17 url: /codex/security/cli/ci/github#save-reports-and-upload-sarif

18 - label: Explore CI/CD integrations and enforcement options

19 url: /codex/security/cli/ci

20---

21 

22> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

23 

24Instead of enforcing security reviews through Codex, it is also possible to create custom workflows that run the Codex Security CLI. We’ve packaged this workflow to easily be used as a GitHub Action.

25```yaml

26name: Codex Security review

27on:

28 workflow_dispatch:

29 schedule:

30 - cron: '23 7 * * 1' # Mondays at 07:23 UTC

31 

32permissions:

33 contents: read

34 

35jobs:

36 security:

37 runs-on: ubuntu-24.04

38 steps:

39 - name: Set up the Ubuntu sandbox

40 run: |

41 sudo apt-get update

42 sudo apt-get install --yes bubblewrap apparmor-profiles

43 sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

44 

45 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

46 with:

47 persist-credentials: false

48 - uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0

49 with:

50 model: gpt-5.6-sol

51 effort: high

52 env:

53 OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

54```

55 

56These workflows can also be applied to other source code management tools like GitLab, BitBucket, or Jenkins. Take a look at our documentation page to learn more: [Run Codex Security in CI](https://developers.openai.com/codex/security/cli/ci).

1---

2name: Manage supply chain risk in the CI/CD

3tagline: Investigate dependency alerts and check package updates for security risks.

4summary: Assess how third-party dependencies affect your application’s security

5 with Codex Security CLI. Triage and validate Dependabot alerts, and run

6 security scans when packages are introduced or updated.

7bestFor:

8 - Application security teams deciding which dependency alerts require action.

9 - Developers assessing newly introduced packages or dependency updates.

10 - Platform teams adding dependency-triggered security scans to their CI/CD

11 pipelines.

12relatedLinks:

13 - label: Triage Dependabot alerts against your repository

14 url: /codex/security/plugin/triage-backlog

15 - label: Validate dependency findings from the CLI

16 url: /codex/security/cli/reference#codex-security-validate-and-codex-security-patch

17 - label: Configure pull-request scans and Dependabot bot access

18 url: /codex/security/cli/ci/github#scan-pull-request-changes

19---

20 

21> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

22 

23You can leverage the Codex Security CLI to assess dependencies in the codebase, such as when a new dependency is introduced or a version is bumped. This is extremely useful in preventing vulnerable packages from presenting supply chain risk. The way to achieve this is through deploying the Codex Security CLI as commands within custom workflows.

24 

25## Validating Dependabot alerts

26 

27 

28Codex Security provides a skill for validating existing third-party vulnerabilities, including Dependabot, for reachability and exploitability. You can invoke the skill directly in the UI or through the CLI.

29 

30![Codex invoking the triage-finding skill for Dependabot alerts.](https://developers.openai.com/images/codex/secure-sdlc/dependabot-triage.webp)

31 

32Codex will triage each of the Dependabot alerts and subsequently present a ledger of each presented risk with a reason why the alert was validated or not.

33 

34![Dependabot triage results with verdicts and static rationale.](https://developers.openai.com/images/codex/secure-sdlc/dependabot-ledger.webp)

35 

36## Running scans when package versions change

37 

38It is also possible to run security scans against the latest version of a dependency when the version is changed.

39 

40```yaml

41name: Codex Security dependency scan

42 

43on:

44 pull_request:

45 paths:

46 - package.json

47 - package-lock.json

48 

49permissions:

50 contents: read

51 

52jobs:

53 scan:

54 name: Scan dependency changes

55 if: github.event.pull_request.head.repo.full_name == github.repository

56 runs-on: ubuntu-24.04

57 timeout-minutes: 45

58 steps:

59 - name: Set up the Ubuntu sandbox

60 run: |

61 sudo apt-get update

62 sudo apt-get install --yes bubblewrap apparmor-profiles

63 sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

64 

65 - name: Set up Node.js

66 uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7

67 with:

68 node-version: "26"

69 

70 - name: Set up Python

71 uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7

72 with:

73 python-version: "3.14"

74 

75 - name: Install Codex Security

76 run: |

77 set -euo pipefail

78 npm install \

79 --prefix "$RUNNER_TEMP/codex-security" \

80 --ignore-scripts \

81 --no-audit \

82 --no-fund \

83 @openai/codex-security

84 

85 - name: Verify Codex Security

86 env:

87 CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security

88 run: |

89 set -euo pipefail

90 test -x "$CODEX_SECURITY_BIN"

91 "$CODEX_SECURITY_BIN" --version

92 

93 - name: Check out the pull request

94 uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7

95 with:

96 ref: ${{ github.event.pull_request.head.sha }}

97 fetch-depth: 0

98 persist-credentials: false

99 

100 - name: Install project dependencies

101 run: |

102 set -euo pipefail

103 npm ci --ignore-scripts --no-audit --no-fund

104 

105 - name: Run full repository scan

106 env:

107 OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

108 CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security

109 CODEX_SECURITY_STATE_DIR: ${{ runner.temp }}/codex-security-state

110 SCAN_DIR: ${{ runner.temp }}/codex-security-results

111 run: |

112 set -euo pipefail

113 "$CODEX_SECURITY_BIN" scan . \

114 --auth api-key \

115 --output-dir "$SCAN_DIR" \

116 --fail-on-severity high \

117 --json > "$RUNNER_TEMP/codex-security.json"

118 

119 - name: Preserve scan results

120 if: always()

121 uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7

122 with:

123 name: codex-security-dependency-results

124 path: |

125 ${{ runner.temp }}/codex-security-results

126 ${{ runner.temp }}/codex-security.json

127 if-no-files-found: warn

128 retention-days: 7

129```

1---

2name: Review code changes in Codex Desktop

3tagline: Inspect changes and investigate security findings while you work.

4summary: Start a security review from Codex or your repository’s Codex project.

5bestFor:

6 - Developers checking uncommitted changes while the implementation is still

7 fresh in their minds.

8 - Engineers reviewing a commit, branch, or pull-request change set from a

9 local checkout.

10 - Reviewers who want to investigate findings alongside the affected code

11 before deciding what to fix.

12starterPrompt:

13 title: Starter prompt

14 body: Please run a $codex-security:security-diff-scan on [Github repository URL]

15relatedLinks:

16 - label: Install the Codex Security plugin

17 url: /codex/security/plugin

18 - label: Review local changes, commits, and pull requests

19 url: /codex/security/plugin/code-changes#run-a-manual-review

20 - label: Use the Security workbench

21 url: /codex/security/plugin/workbench

22---

23 

24> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

25 

26For a more interactive experience reviewing PRs or uncommitted changes, you can execute reviews through the security tab within Codex.

27 

28![The Security workbench with the Changes scan type selected.](https://developers.openai.com/images/codex/secure-sdlc/changes-scan.webp)

29 

30Alternatively, you can prompt Codex within the repository project of Codex by invoking the skill.

31 

32![Security Diff Scan prompt for the North Star Bank example repository.](https://developers.openai.com/images/codex/secure-sdlc/desktop-review-prompt.webp)

1---

2name: Run security reviews from the CLI

3tagline: Review selected code changes and inspect security evidence from your terminal.

4summary: Use Codex Security CLI to review uncommitted work or changes on a branch.

5bestFor:

6 - Developers checking local work or branch changes from their terminal.

7 - Application security teams assessing selected services, packages, and their

8 consumers in a monorepo.

9 - Engineers investigating existing GitHub code-scanning alerts against their

10 repository.

11relatedLinks:

12 - label: Set up and authenticate the Codex Security CLI

13 url: /codex/security/cli

14 - label: Select changes, revisions, and paths to scan

15 url: /codex/security/cli/reference#select-the-scan-target

16 - label: Validate existing findings from the CLI

17 url: /codex/security/cli/reference#codex-security-validate-and-codex-security-patch

18---

19 

20> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

21 

22## Reviewing uncommitted local work

23 

24You can use the CLI to review uncommitted local work with seeded context about the repository and security policies.

25 

26Run the examples in the same shell from your Git checkout. They assume your security policy is in `SECURITY.md` and your supporting documents are in `docs/security/`. The setup creates a temporary directory for scan results.

27 

28```bash

29northstar_repo="$(git rev-parse --show-toplevel)"

30northstar_kb="$northstar_repo/docs/security"

31northstar_results="$(mktemp -d)"

32```

33 

34```bash

35npx @openai/codex-security scan "$northstar_repo" \

36 --working-tree \

37 --base HEAD \

38 --knowledge-base "$northstar_repo/SECURITY.md" \

39 --knowledge-base "$northstar_kb" \

40 --output-dir "$northstar_results/working-tree"

41```

42 

43This reviews staged and unstaged changes relative to `HEAD`.

44 

45Before starting, be sure to confirm that the working tree contains the change you intend to assess. Unrelated edits broaden the investigation and can make it harder to connect the findings to the question that prompted the review.

46 

47## Reviewing PRs or branch commits

48 

49Another option is to review a PR or branch for security issues. Check out the branch to review and fetch its target branch. This example uses `origin/main`.

50 

51```bash

52northstar_pr_base="$(git -C "$northstar_repo" merge-base origin/main HEAD)"

53 

54npx @openai/codex-security scan "$northstar_repo" \

55 --diff "$northstar_pr_base" \

56 --head HEAD \

57 --knowledge-base "$northstar_repo/SECURITY.md" \

58 --knowledge-base "$northstar_kb" \

59 --output-dir "$northstar_results/branch"

60```

61 

62Note that a diff scan evaluates the proposed changes and does not scan the entire repository. Once complete, the output directory will contain the following files:

63 

64- `report.md`: readable review

65 

66- `scan-manifest.json`: confirms the exact base, head, target, and artifacts

67 

68- `findings.json`: presents the severity, confidence, locations, and remediation

69 

70- `coverage.json`: identifies the reviewed surfaces, exclusions, deferred work, and completeness

71 

72 

73## Scanning monorepos

74 

75In a monorepo, a change to a shared library can affect multiple services. Codex should receive enough context to review those interactions, while CI determines which components and checks are required.

76 

77## Repository context

78 

79Keep shared engineering instructions in `AGENTS.md` and security expectations in `SECURITY.md`. A typical repository could look like this:

80 

81```text

82monorepo/

83├── AGENTS.md

84├── SECURITY.md

85├── docs/security/

86│ ├── architecture.md

87│ └── threat-model.md

88├── packages/auth/

89└── services/

90 ├── billing/

91 └── reporting/

92```

93 

94Use existing ownership and build metadata to connect each component to its dependencies, consumers, and tests. For example, a change to `packages/auth` may require reviewing both services even when their files are unchanged. This scope mapping is maintained by your organization; it is not automatically configured by adding Codex.

95 

96## Component assessment

97 

98Large repositories may not always require scanning the entire codebase for each PR. One option is to use a path scan when a monorepo contains separate services or packages. Repeat --path to assess a shared library and its consumers together.

99 

100```bash

101npx @openai/codex-security scan "$northstar_repo" \

102 --path packages/auth \

103 --path services/billing \

104 --path services/reporting \

105 --knowledge-base "$northstar_repo/SECURITY.md" \

106 --knowledge-base "$northstar_kb" \

107 --output-dir "$northstar_results/paths"

108```

109 

110This scans only the selected paths rather than the entire repository.

111 

112## PR and diff scanning

113 

114For a PR, use its exact base and head commit hashes from authenticated GitHub metadata. Both revisions and their history must be available in the checkout. The following example reuses the variables above and saves the diff results separately:

115 

116```bash

117BASE_SHA="<full PR base commit SHA>"

118HEAD_SHA="<full PR head commit SHA>"

119 

120BASE_REVISION="$(

121 git -C "$northstar_repo" merge-base "$BASE_SHA" "$HEAD_SHA"

122)" || exit

123 

124npx @openai/codex-security scan "$northstar_repo" \

125 --diff "$BASE_REVISION" \

126 --head "$HEAD_SHA" \

127 --knowledge-base "$northstar_kb" \

128 --auth chatgpt \

129 --output-dir "$northstar_results/pr"

130```

131 

132A diff scan focuses on the proposed changes. If a shared-library change requires broader consumer review, also run the component assessment against a clean checkout of that PR’s head revision. Keep the results distinct: `--diff` and `--path` are separate scan modes and cannot be combined.

133 

134## Scanning alerts from GitHub

135 

136You can also assess code scanning alerts from the default branch using the Codex Security CLI.

137 

138```bash

139northstar_github_repository="example/northstar"

140northstar_github_alerts="$northstar_results/github-alerts.json"

141 

142# Import all open alerts as complete JSON.

143npx @openai/codex-security import github "$northstar_github_repository" \

144 --format json \

145 > "$northstar_github_alerts"

146 

147# Or import a selected subset.

148npx @openai/codex-security import github "$northstar_github_repository" \

149 --github-alert 12 \

150 --github-alert 18 \

151 --format json \

152 > "$northstar_github_alerts"

153 

154# Run from the corresponding local repository; imported contents are data.

155cd "$northstar_repo"

156npx @openai/codex-security validate "$northstar_github_alerts"

157```

1---

2name: Set up security context

3tagline: Define what to protect, which rules to check, and what to report.

4summary: Learn how to prepare and configure the context Codex needs for security

5 reviews and scans.

6skills:

7 - token: $codex-security:threat-model

8 url: /codex/security/threat-model

9 description: Create a threat model of your application’s assets, entry points,

10 security boundaries, and assumptions.

11 - token: $codex-security:define-security-policy

12 url: /codex/security/plugin/changelog#define-repository-security-policy

13 description: Generate and seed a security policy within your repository.

14bestFor:

15 - Developers preparing a repository for security reviews and scans.

16 - Application security teams documenting system risks, security requirements,

17 and reporting criteria.

18 - Teams making architecture, engineering, and operational knowledge available

19 to security agents.

20relatedLinks:

21 - label: Add threat-model context to security reviews

22 url: /codex/security/security-review#add-threat-model-context

23 - label: Configure SECURITY.md guidance for scans

24 url: /codex/security/plugin/scans#configure-the-scan

25 - label: Customize engineering instructions with AGENTS.md

26 url: /codex/agent-configuration/agents-md

27 - label: Supply architecture and security documents to CLI scans

28 url: /codex/security/cli/reference#add-security-context

29---

30 

31> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

32 

33## Differences among threat models, AGENTS.md, SECURITY.md, and knowledge bases

34 

35[`AGENTS.md`](https://developers.openai.com/codex/agent-configuration/agents-md) keeps shared engineering instructions that establish consistent expectations. `SECURITY.md` tells Codex how your organization wants that reality evaluated and reported. A threat model describes the security reality of the system. They overlap, but the threat model is usually one part of the broader policy.

36 

37For example, a threat model would include details about assets, entry points, attacker-controlled inputs, trust boundaries, authentication assumptions, privileged operations, and risky components.

38 

39```markdown

40# Threat Model

41 

42The public API accepts untrusted JSON and file uploads.

43Requests cross from the internet-facing API into internal billing and

44identity services. Attackers are unauthenticated users or compromised

45tenant accounts. Protect tenant data, billing mutations, and service credentials.

46```

47 

48The `security.md` tells Codex how your organization wants that reality evaluated and reported.

49 

50```markdown

51# Security Policy

52 

53## Security Invariants

54 

55- Every billing mutation must be authorized for the active tenant.

56- Uploaded content must be parsed within explicit size and resource limits.

57- Service credentials must never be returned to clients.

58 

59## Reportable Findings

60 

61Report realistic violations of tenant isolation, authentication bypass,

62unsafe parsing, secret exposure, or unauthorized billing mutations.

63 

64## Severity Context

65 

66Cross-tenant access is Critical.

67Single-tenant unauthorized mutation is High.

68 

69## Out of Scope

70 

71Development-only tools that cannot be included in production builds.

72```

73 

74Finally, a knowledge base supplies supporting documents to particular scans. This can include architecture documents, policies, additional threat models, or operational context that the CLI scanner should consider. Here’s an example of a Markdown architecture document seeded for the CLI scanner.

75 

76```markdown

77# Payment Service Security Context

78 

79## Purpose

80 

81The payment service creates charges, issues refunds, and stores references

82to payment-provider customers. It does not store full card numbers or CVVs.

83 

84## Deployment and Exposure

85 

86- `POST /api/payments` is internet-facing through the API gateway.

87- `POST /internal/refunds` is reachable only from the support service.

88- Background workers consume messages from the `payment-events` queue.

89- The service runs with access to the payment-provider API and billing database.

90 

91## Authentication and Authorization

92 

93- Public endpoints use JWTs issued by the identity service.

94- The API gateway validates signatures, issuer, and expiration.

95- This service remains responsible for tenant authorization.

96- Internal requests use workload identity; network location alone is not trusted.