TOKEN HIERARCHY GUIDE¶

Quick Reference for Token Selection in CODEX_MASTER_KEY Implementation

Document Version: 1.0.0 Date: 2026-02-17 Target Audience: Developers, Script Authors, Workflow Authors

🎯 Quick Start: Which Token Should I Use?¶

The Three-Token Hierarchy¶

Token	Level	Use When	Common Operations
CODEX_MASTER_KEY	Level 3 (Critical)	Org-level admin operations, workflow dispatch, critical changes	Create org variables, update workflows, rotate tokens
CODEX_BACKUP_TOKEN	Level 2 (Elevated)	Elevated repo operations, cross-repo actions, elevated scopes	Manage repo variables, create check runs, read workflow files
GITHUB_TOKEN	Level 1 (Standard)	Normal CI/CD operations, public info, repo-scoped actions	Read public data, create PR comments, update commit status

📊 Token Scope Comparison¶

Operations Matrix: Which Token for Each Operation?¶

Operation	GitHub_TOKEN	CODEX_BACKUP_TOKEN	CODEX_MASTER_KEY	Recommended
Read Organization Variables	❌	✅	✅	Level 2+
Create Organization Variables	❌	❌	✅	Level 3
Read Repository Variables	✅	✅	✅	Level 1
Create Repository Variables	✅	✅	✅	Level 1
Update Workflow Files	❌	✅	✅	Level 2+
Dispatch Workflow Run	❌	❌	✅	Level 3
Read Public Secrets List	✅	✅	✅	Level 1
Access Repository Secrets	✅	✅	✅	Level 1

Scope Details for Each Token¶

GITHUB_TOKEN (Level 1 - Standard)

Scopes: public_repo, repo:status, repo_deployment, security_events
Usage: Standard CI/CD operations, GitHub Actions workflows
Lifespan: Automatically created per workflow run (60 minutes)
Rate Limit: 1,000 requests/hour per action
Best For: Reading public data, updating PR status, creating comments

CODEX_BACKUP_TOKEN (Level 2 - Elevated)

Scopes: repo (full), admin:org_hook (read), workflow, actions:read_self
Permissions: Read/write all repos, read org hooks, manage actions
Lifespan: Long-lived (generated during setup, rotated quarterly)
Rate Limit: 5,000 requests/hour
Best For: Creating variables, managing workflows, cross-repo coordination

CODEX_MASTER_KEY (Level 3 - Critical)

Scopes: admin:org, admin:repo_hook, workflow, repo:full, admin:ssh_signing_key
Permissions: Full org admin, all repo operations, emergency procedures
Lifespan: Emergency use only (auto-rotated after use, 30-minute window)
Rate Limit: 10,000 requests/hour (org-level burst: 100/minute)
Best For: Organization variables, token rotation, emergency dispatch

🔄 Decision Tree: Choosing Your Token¶

START: I need to perform an operation

├─ Does it involve ORGANIZATION-level data?
│  ├─ YES: Go to "Organization Operations" (see below)
│  └─ NO: Go to "Repository Operations" (see below)

ORGANIZATION OPERATIONS:
├─ Creating or modifying ORG VARIABLES?
│  ├─ YES: Use CODEX_MASTER_KEY (Level 3)
│  └─ NO: Use CODEX_BACKUP_TOKEN (Level 2)
├─ Reading ORG data only?
│  └─ Use CODEX_BACKUP_TOKEN (Level 2)
├─ Emergency: Rotating tokens or dispatch override?
│  └─ Use CODEX_MASTER_KEY (Level 3)

REPOSITORY OPERATIONS:
├─ Creating REPO VARIABLES?
│  └─ Use GITHUB_TOKEN (Level 1) - sufficient scope
├─ Updating WORKFLOW FILES?
│  ├─ Org-level changes: Use CODEX_MASTER_KEY (Level 3)
│  ├─ Repo-level changes: Use CODEX_BACKUP_TOKEN (Level 2)
│  └─ Status/comment: Use GITHUB_TOKEN (Level 1)
├─ Reading repo secrets/variables?
│  └─ Use GITHUB_TOKEN (Level 1) - sufficient scope
├─ Accessing GitHub API?
│  ├─ Admin operations: Use CODEX_BACKUP_TOKEN (Level 2+)
│  ├─ Standard operations: Use GITHUB_TOKEN (Level 1)
│  └─ Org admin ops: Use CODEX_MASTER_KEY (Level 3)

💡 Common Use Cases & Examples¶

Use Case 1: Developer Reading Repository Variables¶

Scenario: Your script needs to read a deployment target variable from a repository.

Decision: Use GITHUB_TOKEN (Level 1) - Sufficient scope for reading repo variables - Automatically available in workflows - No special setup needed

Example:

import os
import requests

# GITHUB_TOKEN is automatically available in GitHub Actions
token = os.environ.get('GITHUB_TOKEN')
repo = os.environ.get('GITHUB_REPOSITORY')
owner, repo_name = repo.split('/')

# Read repository variable
url = f"https://api.github.com/repos/{owner}/{repo_name}/actions/variables"
headers = {"Authorization": f"token {token}"}

response = requests.get(url, headers=headers)
variables = response.json()

if response.status_code == 200:
    for var in variables.get('variables', []):
        if var['name'] == 'DEPLOYMENT_TARGET':
            print(f"Target: {var['value']}")
else:
    print(f"Error: {response.status_code}")

Use Case 2: CI Pipeline Creating a Repository Variable¶

Scenario: Your CI pipeline needs to create a new environment-specific variable in the repository.

Decision: Use GITHUB_TOKEN (Level 1) - Repository variable creation is repo-scoped - No org-level access required - GITHUB_TOKEN has sufficient scope

Example:

#!/bin/bash

# Create a repository variable using GITHUB_TOKEN
TOKEN=${GITHUB_TOKEN}
REPO=${GITHUB_REPOSITORY}
OWNER=$(echo $REPO | cut -d'/' -f1)
REPO_NAME=$(echo $REPO | cut -d'/' -f2)

VARIABLE_NAME="BUILD_ENVIRONMENT"
VARIABLE_VALUE="production"

curl -X POST \
  -H "Authorization: token ${TOKEN}" \
  -H "Accept: application/vnd.github.v3+json" \
  "https://api.github.com/repos/${OWNER}/${REPO_NAME}/actions/variables" \
  -d @- <<EOF
{
  "name": "${VARIABLE_NAME}",
  "value": "${VARIABLE_VALUE}"
}
EOF

Use Case 3: Workflow Creating Organization-Level Variable¶

Scenario: Your deployment workflow needs to create an organization-wide variable that multiple repositories will use.

Decision: Use CODEX_MASTER_KEY (Level 3) - Organization variables require org admin scope - Only CODEX_MASTER_KEY has sufficient permission - Requires special setup and request

Example:

on

name="__codelineno-6-1">name: Create Organization Variable class="p">: workflow_dispatch: inputs: variable_name: description: Name of organization variable required: true variable_value: description: Value of organization variable required: true >jobs: create-org-variable: runs-on: ubuntu-latest steps: - name: Create organization variable env: ORG_TOKEN: ${{ secrets.CODEX_MASTER_KEY }} # Requires elevated access GITHUB_ORGANIZATION: 'aries-serpent' run: | VARIABLE_NAME="${{ github.event.inputs.variable_name }}" VARIABLE_VALUE="${{ github.event.inputs.variable_value }}" curl -X POST \ -H "Authorization: token ${ORG_TOKEN}" \ -H "Accept: application/vnd.github.v3+json" \ "https://api.github.com/orgs/${GITHUB_ORGANIZATION}/actions/variables" \ -d "{\"name\":\"${VARIABLE_NAME}\",\"value\":\"${VARIABLE_VALUE}\"}"

Use Case 4: Script with Safe Fallback Token Handling¶

Scenario: Your utility script needs to handle token selection gracefully with fallback logic.

Decision: Use token resolver utility (handles fallback automatically)

Example:

from scripts.ci._token_resolver import get_token, validate_token_scope

def read_organization_variables():
    """Read org variables with proper token selection."""

    # Get appropriate token for org read operation
    # Falls back: CODEX_MASTER_KEY → CODEX_BACKUP_KEY → GH_TOKEN → GITHUB_TOKEN
    token, token_source = get_token(required_elevated=True)

    if not token:
        raise Exception("No suitable token available for org variable read")

    # Validate token has required scope
    is_valid, msg = validate_token_scope(token, ['admin:org_hook'])
    if not is_valid:
        raise Exception(f"Token validation failed: {msg}")

    # Perform operation with selected token
    import requests
    url = "https://api.github.com/orgs/aries-serpent/actions/variables"
    headers = {"Authorization": f"token {token}"}

    response = requests.get(url, headers=headers)
    return response.json() if response.status_code == 200 else None

Use Case 5: Handling Token Scope Errors¶

Scenario: Your operation fails with a scope error - you need to understand why and recover.

Decision: Check token level requirements and recover

Example:

import requests
import logging

def update_workflow_with_retry():
    """Update workflow file with intelligent token fallback."""

    operation_requires_levels = ['elevated', 'critical']  # Levels 2 or 3

    from scripts.ci._token_resolver import get_token

    # Try each token level from highest to lowest
    for level in operation_requires_levels:
        token = get_token(required_level=level)

        if not token:
            logging.warning(f"No {level} token available, trying lower level")
            continue

        try:
            # Attempt workflow update
            response = requests.patch(
                "https://api.github.com/repos/owner/repo/contents/.github/workflows/ci.yml",
                headers={"Authorization": f"token {token}"},
                json={
                    "message": "Update workflow",
                    "content": new_workflow_content,
                    "sha": current_sha
                }
            )

            if response.status_code == 200:
                logging.info(f"Workflow updated using {level} token")
                return True

            elif response.status_code == 403:
                logging.warning(f"Insufficient scope at {level}, trying lower")
                continue

            else:
                logging.error(f"Unexpected error: {response.status_code}")
                raise Exception(f"HTTP {response.status_code}: {response.text}")

        except Exception as e:
            logging.debug(f"Attempt with {level} token failed: {e}")
            continue

    raise Exception("No suitable token available for workflow update")

⚠️ Error Handling & Recovery¶

Error 1: "Token scope insufficient for this request" (403)¶

Root Cause: Using a lower-level token than required for the operation.

Solution: 1. Check which operation you're performing 2. Reference the Operations Matrix above 3. Use a higher-level token (see Decision Tree) 4. Re-run the operation

Example:

# WRONG: Trying to read org variables with GITHUB_TOKEN
token = os.environ.get('GITHUB_TOKEN')  # Level 1 - insufficient

# RIGHT: Request CODEX_BACKUP_TOKEN for org read
from scripts.ci._token_resolver import get_token
token = get_token(required_level='elevated')  # Level 2

Error 2: "Token expired or revoked"¶

Root Cause: Token has been manually revoked or automatically rotated.

Solution: 1. For GITHUB_TOKEN: Automatically renewed in next workflow run 2. For CODEX_BACKUP_TOKEN: Contact repo admin for reissue (quarterly rotation) 3. For CODEX_MASTER_KEY: Automatically managed, use emergency procedure

Example Recovery Script:

#!/bin/bash

# Check if token is valid
TOKEN=$1
if [ -z "$TOKEN" ]; then
    echo "Error: No token provided"
    exit 1
fi

# Attempt simple API call to validate
response=$(curl -s -I -H "Authorization: token ${TOKEN}" \
    https://api.github.com/user)

if echo "$response" | grep -q "401 Unauthorized"; then
    echo "Token is invalid/revoked. Contact repo admin."
    exit 1
elif echo "$response" | grep -q "200 OK"; then
    echo "Token is valid"
    exit 0
else
    echo "Token validation inconclusive"
    exit 1
fi

Error 3: "Permission denied" (403) vs "Token scope insufficient"¶

Key Difference: - Scope Insufficient: Token doesn't have permission TYPE (e.g., lacks 'admin:org') - Permission Denied: User/token type doesn't have role permission (e.g., not org owner)

Diagnosis:

# Check scope error
if "insufficient" in error_message.lower():
    print("Need different token with different scope")
    print("Try: CODEX_BACKUP_TOKEN or CODEX_MASTER_KEY")

# Check permission error  
elif "permission" in error_message.lower():
    print("Current user lacks role permission")
    print("Contact repo admin or use elevated token")

Error 4: Rate Limit Exceeded (429)¶

Root Cause: Exceeded request limit for token level.

Rate Limits by Token: - GITHUB_TOKEN: 1,000 requests/hour (repo scope) - CODEX_BACKUP_TOKEN: 5,000 requests/hour - CODEX_MASTER_KEY: 10,000 requests/hour

Solution: Implement exponential backoff

import time
import requests

def api_call_with_retry(url, token, max_retries=3):
    """Make API call with automatic retry on rate limit."""

    for attempt in range(max_retries):
        headers = {"Authorization": f"token {token}"}
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        elif response.status_code == 429:
            # Rate limited - use exponential backoff
            wait_time = 2 ** attempt  # 1s, 2s, 4s
            print(f"Rate limited. Waiting {wait_time}s before retry...")
            time.sleep(wait_time)
            continue

        else:
            raise Exception(f"API Error: {response.status_code}")

    raise Exception("Max retries exceeded")

🔐 Security Best Practices¶

1. Token Environment Variables¶

✅ DO: Keep tokens in environment variables

token = os.environ.get('GITHUB_TOKEN')

❌ DON'T: Hardcode tokens in scripts

# WRONG!
token = "******"

2. Logging Token Usage Safely¶

✅ DO: Log operation without exposing token

logging.info(f"Using {token_level} token for org variable read")

❌ DON'T: Log token values

# WRONG!
logging.info(f"Using token: {token}")

3. Token Scope Validation¶

✅ DO: Validate scope before operation

from scripts.ci._token_resolver import validate_token_scope

if not validate_token_scope(token, ['admin:org']):
    raise Exception("Token lacks required scope")

❌ DON'T: Assume token has sufficient scope

# WRONG! - Might fail with 403
requests.get(url, headers={"Authorization": f"token {token}"})

4. Error Messages¶

✅ DO: Include helpful guidance in errors

if response.status_code == 403:
    raise Exception(
        "Scope insufficient for this operation. "
        "Use CODEX_BACKUP_TOKEN or CODEX_MASTER_KEY. "
        "See: TOKEN_HIERARCHY_GUIDE.md"
    )

❌ DON'T: Expose token in error messages

# WRONG!
raise Exception(f"API failed with token {token}: {response.text}")

SCRIPT_TOKEN_docs/api/reference/INTEGRATION.md - How to implement token resolution in scripts
WORKFLOW_TOKEN_PATTERNS_UPDATE.md - Token patterns for GitHub Actions workflows
API_VARIABLE_OPERATIONS.md - Complete API guide for variable operations
CI_CD_TOKEN_TROUBLESHOOTING.md - Troubleshooting guide for token issues
CUSTOM_AGENT_TOKEN_GUIDANCE.md - Token requirements for custom agents

✅ Quick Reference Checklist¶

Use this checklist when choosing a token:

Have I identified if this is an org-level or repo-level operation?
Have I checked the Operations Matrix above?
Have I followed the Decision Tree?
Have I chosen the lowest-level token that works (principle of least privilege)?
Have I verified the token is available in my environment?
Have I implemented error handling for token failures?
Have I ensured I'm not logging token values?
Have I tested with the actual token level I'm using?

📞 Getting Help¶

For token selection questions: 1. Check the Decision Tree (above) 2. Check the Operations Matrix (above) 3. See related documentation for your use case

For token errors: 1. See "Error Handling & Recovery" section 2. Check CI_CD_TOKEN_TROUBLESHOOTING.md 3. Contact repo admin with error message

For implementation questions: 1. See code examples in "Common Use Cases" section 2. Check SCRIPT_TOKEN_docs/api/reference/INTEGRATION.md for patterns 3. Check WORKFLOW_TOKEN_PATTERNS_UPDATE.md for workflows

Document Version: 1.0.0 Last Updated: 2026-02-17 Maintained By: CODEX_MASTER_KEY Implementation Team Status: Ready for Use

TOKEN HIERARCHY GUIDE¶

🎯 Quick Start: Which Token Should I Use?¶

The Three-Token Hierarchy¶

📊 Token Scope Comparison¶

Operations Matrix: Which Token for Each Operation?¶

Scope Details for Each Token¶

🔄 Decision Tree: Choosing Your Token¶

💡 Common Use Cases & Examples¶

Use Case 1: Developer Reading Repository Variables¶

Use Case 2: CI Pipeline Creating a Repository Variable¶

Use Case 3: Workflow Creating Organization-Level Variable¶

Use Case 4: Script with Safe Fallback Token Handling¶

Use Case 5: Handling Token Scope Errors¶

⚠️ Error Handling & Recovery¶

Error 1: "Token scope insufficient for this request" (403)¶

Error 2: "Token expired or revoked"¶

Error 3: "Permission denied" (403) vs "Token scope insufficient"¶

Error 4: Rate Limit Exceeded (429)¶

🔐 Security Best Practices¶

1. Token Environment Variables¶

2. Logging Token Usage Safely¶

3. Token Scope Validation¶

4. Error Messages¶

🔗 Related Documentation¶

✅ Quick Reference Checklist¶

📞 Getting Help¶