Connect Codex to LinearB using the Analytics API

Overview

Connect Codex to LinearB using the Analytics API to collect Codex usage and code attribution data and analyze AI adoption and usage in LinearB.

Use this connection if your organization uses ChatGPT Enterprise or Edu with Codex enabled.

Availability: The Codex Analytics API integration is generally available (GA). ChatGPT Business, Plus, and Pro workspaces cannot create the required Admin key. Use the Codex OpenTelemetry integration instead.

Data Provided by Codex

LinearB collects daily, per-user Codex data, including:

Threads and turns
Credits and estimated cost (USD)
Token consumption, including uncached input, cached input, and output tokens
Usage by model
Usage by client, including Desktop, IDE, CLI, cloud, and other clients
Lines added, removed, and committed
Commits

Code attribution: The Analytics API is the source of accepted-lines-of-code data for Codex in LinearB.

Estimated cost: Cost data represents estimated AI consumption in LinearB. It is not the amount billed by your AI provider.

Before You Begin

Before connecting Codex, make sure:

Your organization uses ChatGPT Enterprise or Edu with Codex enabled.
You are a workspace owner or admin, or can obtain an Admin key from one.
You have your ChatGPT Workspace ID.
You have access to AI Tools settings in LinearB.

Create an Admin Key

Open the OpenAI Admin Console.
Go to Credentials → Admin keys.
Click Create new admin key.
Select the ChatGPT workspace you want to connect.
Select Restricted/Custom permissions.
Set Codex analytics API to Read.
Create the Admin key.
Copy and store the key securely.

The required permission grants the codex.enterprise.analytics.read scope.

Important: The Admin key is displayed only once. Copy it when you create it.

Use a ChatGPT Admin key: OpenAI API Platform organization or project keys, Codex access tokens, and service-account tokens cannot be used for this integration.

Find Your Workspace ID

In the ChatGPT Admin Console, open Workspace details and copy the Workspace ID.

The Workspace ID is a UUID that identifies the ChatGPT workspace you are connecting to LinearB.

Multiple workspaces: Each Admin key is scoped to a single ChatGPT workspace. If your organization uses multiple workspaces, create a separate Admin key for each workspace you want to connect.

Connect Codex

In LinearB, go to Settings → Company Settings → AI Tools → Integrations.
Click Add New.
Select Codex as the AI provider.
Select Analytics API as the connection type.
Click Continue.
In Token, paste the ChatGPT Admin key you created.
In Workspace ID, enter the Workspace ID from the ChatGPT Admin Console.
Click Add Integration.

LinearB validates the Admin key and Workspace ID and adds the Codex integration.

Connection type: The connection type is selected during setup and cannot be changed afterward. Other supported integration settings can be modified later.

User Matching

LinearB automatically matches Codex users to LinearB contributors by email. No additional identity mapping is required.

Verify the Connection

After adding the integration, go to Settings → Company Settings → AI Tools → Integrations and select the Codex integration.

A successfully configured integration displays Connected. Codex data becomes available in the supported LinearB AI metrics and dashboards after it is collected and processed.

Edit the Integration

Go to Settings → Company Settings → AI Tools → Integrations.
Select the Codex Analytics API integration.
Click Edit under Main Settings.
Update the supported connection settings.
Save your changes.

The provider and connection type cannot be changed when editing an integration. To use a different connection type, add a new Codex integration.

Troubleshooting

Invalid Key

If LinearB reports that the key is invalid, verify that you entered the ChatGPT Admin key created for the workspace and that it has Codex analytics API → Read permission.

OpenAI API Platform organization or project keys, Codex access tokens, and service-account tokens are not supported.

Workspace Not Found

If LinearB reports Workspace not found, the Admin key is valid but the Workspace ID is incorrect. Copy the Workspace ID again from Workspace details in the ChatGPT Admin Console.

Codex Data Does Not Appear

If the integration is connected but Codex data does not appear:

Confirm that the integration displays Connected.
Confirm that Codex is enabled for the connected ChatGPT workspace.
Verify that the Admin key belongs to the workspace identified by the configured Workspace ID.
Verify that the Admin key has Codex analytics API → Read permission.