enterprise/access-tokens diff

enterprise/access-tokens.md +144 −0 added

Details

1# Access tokens

3Codex access tokens let trusted automation run Codex local with a ChatGPT workspace identity. Use them when a script, scheduled job, or CI runner needs repeatable, non-interactive Codex access.

5Codex access tokens are currently supported for ChatGPT Business and

6 Enterprise workspaces.

8Access tokens are created in the ChatGPT admin console at [Access tokens](https://chatgpt.com/admin/access-tokens). They are tied to the ChatGPT user and workspace that create them, and Codex uses them as agent identities for programmatic local workflows.

10If a Platform API key works for your automation, keep using API key auth. Use

11 Codex access tokens when the workflow specifically needs ChatGPT workspace

12 access, ChatGPT-managed Codex entitlements, or enterprise workspace controls.

14## How access tokens work

16Use an access token when Codex needs to run without a user completing a browser sign-in. The token represents the ChatGPT workspace user who created it, so runs can use that user's Codex access and appear in workspace governance data.

18Codex checks the token when a run starts and ties the run to that workspace identity. Treat the token like any other automation secret: store it in a secret manager, keep it out of logs, and rotate it regularly.

20Use access tokens for:

22- `codex exec` jobs that run from trusted automation.

23- Local scripts that need repeatable, non-interactive Codex runs.

24- Enterprise workflows where usage should be associated with a ChatGPT workspace user instead of an API organization key.

26Main risks to avoid:

28- **Leaked secrets:** anyone with the token can start Codex runs as the token creator. Store tokens in a secret manager, keep them out of logs, and rotate them regularly.

29- **Untrusted runners:** public CI, forked pull requests, or shared machines can expose tokens to people outside your workspace. Use access tokens only on trusted runners.

30- **Shared identities:** one person's token reused across unrelated teams makes ownership and audit trails harder to interpret. Create tokens for a specific workflow owner.

31- **Stale credentials:** long-lived tokens can remain active after the workflow changes. Prefer finite expirations and revoke tokens that are no longer used.

32- **Wrong credential type:** access tokens are for Codex local workflows. Use Platform API keys for general OpenAI API calls.

34## Enable access token creation

36Use the Codex Local controls in workspace settings to turn on access token creation for allowed members.

38<CodexScreenshot

39 alt="Access token access permission in ChatGPT workspace RBAC settings"

40 lightSrc="/images/codex/enterprise/rbac_access_token_access_permission.png"

41 darkSrc="/images/codex/enterprise/rbac_access_token_access_permission_dark.png"

42 maxWidth={847}

43 variant="no-wallpaper"

44/>

461. Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

472. In the Codex Local section, make sure **Allow members to use Codex Local** is turned on.

483. Turn on **Allow members to use Codex access tokens** if all allowed members should be able to create access tokens.

494. If you use custom roles for a narrower rollout, assign the access token permission only to groups that need to create tokens.

51Keep access token creation limited to people or service owners who understand where the token will be stored, which automation will use it, and how it will be rotated.

53## Create an access token

55Use the Access tokens page to name the token and choose when it expires.

571. Go to [Access tokens](https://chatgpt.com/admin/access-tokens).

582. Select **Create**.

60<CodexScreenshot

61 alt="Access tokens page with the Create button"

62 lightSrc="/images/codex/enterprise/access_token_create_header.png"

63 darkSrc="/images/codex/enterprise/access_token_create_header_dark.png"

64 maxWidth={942}

65 variant="no-wallpaper"

66/>

683. Enter a descriptive name, such as `release-ci` or `nightly-docs-check`.

70<CodexScreenshot

71 alt="Create access token modal with fields for name and expiration"

72 lightSrc="/images/codex/enterprise/access_token_creation_modal.png"

73 darkSrc="/images/codex/enterprise/access_token_creation_modal_dark.png"

74 maxWidth={544}

75 variant="no-wallpaper"

76/>

784. Choose an expiration. Prefer a finite expiration such as 7, 30, 60, or 90 days. If you choose **No expiration**, rotate the token on a regular schedule.

795. Select **Create**.

806. Copy the generated access token immediately. You cannot view it again after you close the modal.

817. Store the token in your secret manager or CI secret store.

83The shortest custom expiration is one day. Revoked and expired tokens cannot be used to start new Codex runs.

85## Use an access token with Codex CLI

87For ephemeral automation, store the token in `CODEX_ACCESS_TOKEN` and run Codex normally:

89```bash

90export CODEX_ACCESS_TOKEN="<access-token>"

91codex exec --json "review this repository and summarize the top risks"

92```

94For a persistent local login, pipe the token to `codex login --with-access-token`:

96```bash

97printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token

98codex exec "summarize the last release diff"

99```

100

101`codex login --with-access-token` stores an agent identity credential in Codex auth storage. If you prefer not to persist credentials on the machine, use the `CODEX_ACCESS_TOKEN` environment variable instead.

102

103## Rotate or revoke a token

104

105Rotate access tokens the same way you rotate other automation secrets:

106

1071. Create a replacement token.

1082. Update the secret in the runner, scheduler, or secret manager.

1093. Run a smoke test with the new token.

1104. Revoke the old token from [Access tokens](https://chatgpt.com/admin/access-tokens).

111

112From the Access tokens page, workspace owners and admins can revoke any workspace token. Members with access token permission can revoke only the tokens they created.

113

114## Permission model

115

116Access token permissions are separate from the general Codex local permission. A member can have access to the Codex app, CLI, or IDE extension without being allowed to create access tokens.

117

119| ------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------- | -------------------------------------- |

120| Open [Access tokens](https://chatgpt.com/admin/access-tokens) | Yes | Yes | No |

121| Create access tokens | Yes, for their own ChatGPT workspace identity | Yes, for their own ChatGPT workspace identity | No |

122| List access tokens | Workspace list, including who created each token | Only tokens they created | No |

124| Grant or remove access token permission | Yes | No | No |

125| Manage other Codex enterprise settings | Yes, based on admin role and Codex admin permissions | No, unless separately granted | No |

126

127In short: workspace owners and admins manage access at the workspace level. Members need the access token permission to create and manage their own tokens, but the permission does not grant admin rights or access to other members' tokens.

128

129## Troubleshooting

130

131### The access tokens page returns 404 or forbidden

132

133Ask a workspace owner or admin to confirm that Codex access tokens are enabled and that your role includes the access token permission.

134

135### `codex login --with-access-token` fails

136

137Confirm that you copied the generated access token, not a browser session token or Platform API key. Also confirm that the token has not expired or been revoked.

138

139## Related docs

140

141- [Authentication](https://developers.openai.com/codex/auth)

142- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)

143- [Admin setup](https://developers.openai.com/codex/enterprise/admin-setup)

144- [Governance](https://developers.openai.com/codex/enterprise/governance)

enterprise/access-tokens.md Codex Docs, 2026-05-14 07:00 UTC → 2026-05-14 21:00 UTC