Copilot Coding Agent — Token & Authentication Guide¶
Last Updated: 2026-07-11 Version: v0.2.0
**Last Updated: 2026-06-22
Status: CURRENT (PR #3499 W-125, 2026-03-05 — webhook token requirements added) Audience: Copilot Coding Agent sessions, CI/CD pipeline authors Related:
docs/agent/COGNITIVE_APP_CONNECTION_GUIDE.md,scripts/tools/variable_manager.py
Overview¶
Every Copilot Coding Agent session has access to up to four authentication tokens. Each token has a different scope and capability. This guide explains what each token is, how it reaches your session, how to use it, and what it can and cannot do.
Token Priority & Availability¶
| Priority | Token | Set in workflow | Exported to GITHUB_ENV |
Scope / Capability |
|---|---|---|---|---|
| 1 | CODEX_MASTER_KEY |
Job env: secrets.CODEX_MASTER_KEY |
" Export Auth Tokens" step | Full PAT (classic) — repo scope. Can read/write all GitHub API resources including variables, secrets, and settings. Required for variables API. |
| 2 | CODEX_BACKUP_KEY |
Job env: secrets.CODEX_BACKUP_KEY |
same step | Fallback PAT — same capability as above, used when master key is absent. |
| 3 | AGENT_GITHUB_TOKEN |
Derived from GITHUB_TOKEN |
same step | Alias for GITHUB_TOKEN; stable env var name for agent code. Cannot access variables API. |
| 4 | GITHUB_TOKEN |
Auto-provided by GitHub Actions | Already in env | Scoped installation token. Can push code, comment on PRs, dispatch workflows. Cannot access the Actions Variables API (requires PAT repo scope). |
Webhook operations also accept
CODEX_ADMIN_KEY(a fine-grained PAT with Webhooks:write) as the highest-priority auth source.webhook_configurator.pyresolves tokens in the order:CODEX_ADMIN_KEYCODEX_MASTER_KEY.GITHUB_TOKENcannot manage webhooks.
All four tokens are resolved automatically by BrainClient._auth_header() and
VariableManager._resolve_token() — no manual header construction needed.
How Tokens Reach the Agent Session¶
copilot-setup-steps.yml
job env: block
CODEX_MASTER_KEY: ${{ secrets.CODEX_MASTER_KEY }} job-level only
CODEX_BACKUP_KEY: ${{ secrets.CODEX_BACKUP_KEY }} job-level only
" Export Auth Tokens to Agent Environment" step
echo "CODEX_MASTER_KEY=..." >> $GITHUB_ENV persists to agent
echo "CODEX_BACKUP_KEY=..." >> $GITHUB_ENV persists to agent
echo "AGENT_GITHUB_TOKEN=..." >> $GITHUB_ENV persists to agent
" Start CLI API Server" step
export CODEX_MASTER_KEY="${CODEX_MASTER_KEY:-}" forwarded to uvicorn
export CODEX_BACKUP_KEY="${CODEX_BACKUP_KEY:-}"
export AGENT_GITHUB_TOKEN="${GITHUB_TOKEN:-}"
Copilot Agent process inherits GITHUB_ENV all four tokens available
Why two steps? Job-level
env:values are available to setup steps but are not automatically added toGITHUB_ENV. The " Export Auth Tokens" step bridges this gap by explicitly writing the values to the GITHUB_ENV file that the agent process reads.
Permission Matrix¶
| API Operation | CODEX_MASTER_KEY |
CODEX_BACKUP_KEY |
AGENT_GITHUB_TOKEN / GITHUB_TOKEN |
|---|---|---|---|
| Repo variables — list | requires PAT repo scope |
||
| Repo variables — create/update/delete | requires PAT repo scope |
||
| Environment variables — list | requires PAT repo scope |
||
| Environment variables — create/update/delete | requires PAT repo scope |
||
| Org variables — list | |||
| Org variables — create/update/delete | |||
| Repo secrets — read/write | |||
| Org secrets — read/write | (if org admin) | (if org admin) | |
| Code push / commits | (contents:write) | ||
| Issues / PRs | (issues/pull-requests:write) | ||
| Workflow dispatch | (actions:write) | ||
| GitHub API (read-only) — repos, runs, PRs | |||
| Webhooks — list | (admin:repo_hook) |
(admin:repo_hook) |
403 — requires PAT with admin:repo_hook or fine-grained Webhooks:read |
| Webhooks — create/update/delete | (admin:repo_hook) |
(admin:repo_hook) |
403 — requires CODEX_ADMIN_KEY (Webhooks:write) or CODEX_MASTER_KEY (admin:repo_hook) |
Key constraint: GitHub's Actions Variables API requires a classic PAT with
reposcope OR a fine-grained PAT withVariables: read/write.GITHUB_TOKENcannot access the variables API regardless of theactions:permission level in the workflow.CODEX_MASTER_KEYis the only token in this chain that can manage variables.Summary: Use
CODEX_MASTER_KEYfor any GitHub API call. UseGITHUB_TOKEN/AGENT_GITHUB_TOKENas a fallback for repo/env variable management only.Webhook operations (scripts/ci/webhook_configurator.py) use a dedicated token hierarchy: 1.
CODEX_ADMIN_KEY— fine-grained PAT with Webhooks: write scope (preferred for least-privilege) 2.CODEX_MASTER_KEY— classic PAT withadmin:repo_hookscope (fallback)
GITHUB_TOKENreturns HTTP 403 for all webhook API calls — this is expected and correct. SetCODEX_ADMIN_KEYas a repo/org secret with only Webhooks:read+write to follow least-privilege. Theapply-webhooksjob inagent_infrastructure_manager.ymlalso acceptsWEBHOOK_RECEIVER_URLas a repo variable (not a secret) to override the placeholder URL without editing config files.
Using Tokens in Agent Code¶
1 — Automatic (recommended)¶
from codex.agents.brain_client import BrainClient
brain = BrainClient()
# Auth is auto-injected from CODEX_MASTER_KEY GITHUB_TOKEN priority chain
resp = brain.proxy_request("GET",
"https://api.github.com/repos/Aries-Serpent/_codex_/actions/variables")
2 — VariableManager (repo / env / org variables)¶
from scripts.tools.variable_manager import VariableManager
vm = VariableManager() # auto-resolves best available token
# Repo variables
vm.create_repo_var("Aries-Serpent", "_codex_", "COPILOT_TEST_VAR", "hello_agent")
vm.update_repo_var("Aries-Serpent", "_codex_", "COPILOT_TEST_VAR", "updated_val")
vm.list_repo_vars("Aries-Serpent", "_codex_")
vm.delete_repo_var("Aries-Serpent", "_codex_", "COPILOT_TEST_VAR")
# Environment variables
vm.create_env_var("Aries-Serpent", "_codex_", "production", "MY_ENV_VAR", "val")
# Org variables
vm.create_org_var("Aries-Serpent", "COPILOT_ORG_VAR", "val", visibility="all")
# Live test (create verify update verify delete)
vm.run_live_test("Aries-Serpent", "_codex_")
3 — CLI (bash tool / shell scripts)¶
# List repo variables
python scripts/tools/variable_manager.py list repo Aries-Serpent _codex_
# Create a test variable
python scripts/tools/variable_manager.py create repo Aries-Serpent _codex_ \
COPILOT_TEST_VAR "hello_from_agent"
# Update it
python scripts/tools/variable_manager.py update repo Aries-Serpent _codex_ \
COPILOT_TEST_VAR "updated_value"
# Delete it
python scripts/tools/variable_manager.py delete repo Aries-Serpent _codex_ \
COPILOT_TEST_VAR
# Full live test
python scripts/tools/variable_manager.py test
# Environment variables
python scripts/tools/variable_manager.py list env Aries-Serpent _codex_ production
# Org variables
python scripts/tools/variable_manager.py list org Aries-Serpent
4 — Direct curl via CLI API Server¶
# Auto-injects CODEX_MASTER_KEY (or GITHUB_TOKEN fallback) from server env
curl -s -X POST http://localhost:8765/api/request \
-H "Content-Type: application/json" \
-d '{
"method": "POST",
"url": "https://api.github.com/repos/Aries-Serpent/_codex_/actions/variables",
"body": {"name": "COPILOT_TEST_VAR", "value": "hello_from_agent"}
}'
5 — Check which token is active¶
python3 -c "
import os
priority = ['CODEX_MASTER_KEY','CODEX_BACKUP_KEY','AGENT_GITHUB_TOKEN','GITHUB_TOKEN']
for k in priority:
v = os.environ.get(k, '')
if v:
print(f'Active token: {k} ({len(v)} chars)')
break
else:
print(' No auth token found in environment')
"
Agent Token Delegation¶
When a PR has Agent Token Delegation enabled (checkbox ticked in PR description) and the owner approves the workflow run, the delegation workflow:
- Sets
COPILOT_AGENT_AUTH_ENABLED=truerepo variable - Writes
.codex/agent_auth_session.jsonwith provenance metadata - Updates
COGNITIVE_BRAIN_ALLOWED_ACTORSwith the delegated actors list
{
"issued_at": "2026-03-05T04:44:23Z",
"expires_at": 1772700263,
"issued_by": "agent-auth-delegation",
"run_id": "22702507580",
"pr_number": "3497",
"note": "Provenance-chain token. Allows all agent sessions to bypass owner_approval_guard within TTL."
}
The delegation does not change which auth tokens are available — it changes
what the agent is authorised to do with those tokens (bypasses the
owner_approval_guard gate within the TTL).
Check delegation status:
import json, os, time
session = json.load(open(".codex/agent_auth_session.json"))
expired = int(time.time()) > session.get("expires_at", 0)
print(f"Delegation active: {not expired}")
print(f"Issued by: {session['issued_by']} on {session['issued_at']}")
Troubleshooting¶
403 Resource not accessible by integration¶
Token source GITHUB_TOKEN (no repo scope)
Affected APIs secrets, org variables, some advanced settings
Fix Use CODEX_MASTER_KEY (must be set as org secret)
401 Bad credentials¶
Token source Token is expired or invalid
Fix Re-trigger agent-auth-delegation workflow to refresh session
Or: rotate CODEX_MASTER_KEY org secret
CODEX_MASTER_KEY not in agent process env¶
Symptom python3 -c "import os; print(os.environ.get('CODEX_MASTER_KEY','MISSING'))"
MISSING
Cause " Export Auth Tokens" step was not executed or secret is empty
Fix Verify secrets.CODEX_MASTER_KEY is set in org/repo secrets
Check copilot-setup-steps.yml step " Export Auth Tokens to Agent Environment"
CLI API Server returns 401 for GitHub API calls¶
Symptom POST /api/request {"status_code": 401, ...}
Cause Server process doesn't have CODEX_MASTER_KEY in its env
(setup steps forwarded it to GITHUB_ENV but server started before that step)
Fix Verify step order: " Export Auth Tokens" MUST run BEFORE
" Start CLI API Server".
The server startup step also runs:
export CODEX_MASTER_KEY="${CODEX_MASTER_KEY:-}"
to explicitly forward the key to the uvicorn process.
X-OAuth-Scopes: (empty scopes on GITHUB_TOKEN)¶
Symptom curl -sI -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/ |
grep X-OAuth-Scopes
X-OAuth-Scopes:
Explanation GITHUB_TOKEN is a GitHub Apps installation token, NOT a classic OAuth token.
It has no "scopes" — its permissions come from the workflow permissions: block.
This is NORMAL. The token is valid; empty scopes ≠ no permissions.
Fix Ensure workflow has `actions: write` in permissions: block.
Quick Verification Script¶
Run at the start of every agent session to confirm all tokens and the CLI server are functioning:
python3 - <<'EOF'
import os, sys, json, urllib.request, urllib.error
print("=" * 55)
print(" Copilot Agent Token & CLI Server Verification")
print("=" * 55)
# 1. Token inventory
priority = [
("CODEX_MASTER_KEY", "Full PAT (repo scope)"),
("CODEX_BACKUP_KEY", "Fallback PAT"),
("AGENT_GITHUB_TOKEN", "GITHUB_TOKEN alias"),
("GITHUB_TOKEN", "Actions installation token"),
]
active_token = ""
active_name = ""
for name, desc in priority:
val = os.environ.get(name, "")
status = f" {len(val)} chars" if val else " NOT SET"
print(f" {name:<25} {status:>15} ({desc})")
if val and not active_token:
active_token, active_name = val, name
print(f"\n Active token: {active_name or 'NONE'}")
# 2. GitHub API test
if active_token:
req = urllib.request.Request(
"https://api.github.com/repos/Aries-Serpent/_codex_",
headers={
"Authorization": f"Bearer {active_token}",
"Accept": "application/vnd.github+json",
"X-GitHub-Api-Version": "2022-11-28",
}
)
try:
with urllib.request.urlopen(req, timeout=10) as resp: # nosec
d = json.loads(resp.read())
print(f" GitHub API (repo info): {d['full_name']}")
except urllib.error.HTTPError as e:
print(f" GitHub API (repo info): HTTP {e.code}")
except Exception as e:
print(f" GitHub API (repo info): {e}")
# 3. CLI API server
try:
req = urllib.request.Request("http://localhost:8765/api/health")
with urllib.request.urlopen(req, timeout=3) as resp: # nosec
h = json.loads(resp.read())
print(f" CLI API server (:8765): status={h.get('status')}")
except Exception as e:
print(f" CLI API server (:8765): {e}")
# 4. Delegation status
try:
sess = json.load(open(".codex/agent_auth_session.json"))
import time
expired = int(time.time()) > sess.get("expires_at", 0)
flag = " EXPIRED" if expired else " ACTIVE"
print(f" Agent token delegation: {flag} (issued {sess.get('issued_at','')})")
except Exception:
print(" Agent token delegation: session file not found")
print("=" * 55)
EOF
Related Documentation¶
| Document | Purpose |
|---|---|
docs/agent/COGNITIVE_APP_CONNECTION_GUIDE.md |
CLI API Server full reference + variable management |
scripts/tools/variable_manager.py |
CRUD tool — repo/env/org variables |
tests/agents/test_variable_management.py |
Unit test suite for variable manager |
src/codex/agents/brain_client.py |
BrainClient — typed Python client |
.github/workflows/copilot-setup-steps.yml |
Setup steps — token export implementation |
.github/workflows/agent-auth-delegation.yml |
Delegation workflow — session token issuance |
.codex/agent_auth_session.json |
Active delegation session metadata |