# OpenAI Administration API — atlas

Status: DOCUMENTED for all 124 operations (OpenAPI spec v2.3.0); every GET we could probe is ACCOUNT_RESTRICTED (our project key gets HTTP 403 — 401 for audit logs — Missing scopes: api.management.read etc.). No Admin key is available, so nothing below is LIVE_VERIFIED except the exact error shapes. No mutating admin call was ever issued.

Sources: Administration overview · Admin APIs guide · Production best practices → organization · Spend limits · Mutual TLS · IP allowlist · Your data (retention / residency) · OpenAPI sources/openai/openapi/openapi-master.yaml (all /organization/* + /projects/* paths) · SDK surfaces sources/openai/openapi/{python,node}-sdk-api.md.

Last verified: 2026-09-18 (live probes: 14 admin GETs, all 401/403; details in tmp-live/openai-admin/ and reports/live-requests.jsonl).

Machine-readable twins: generated/fragments/endpoints/openai-admin.json (124 endpoints), generated/fragments/parameters/openai-admin.json (431 parameters), generated/fragments/audit-log-events/openai-audit-log-events.json (149 event types).

# 1. Model of the Admin API

# 2. Endpoint catalogue

Legend: * = required parameter; SDK column = Python method (Node is the camelCase twin, e.g. client.admin.organization.auditLogs.list).

# Organization admin api keys

# Organization audit logs

# Certificates (Mutual TLS)

# Usage & costs

# Organization data retention

# Organization groups

# Organization role bindings

# Group membership

# Organization invites

# Organization projects

# Project api keys

# Project archive

# Project data retention

# Project groups

# Project hosted tool permissions

# Project model permissions

# Project rate limits

# Project service accounts

# Project spend alerts

# Project users

# Organization roles

# Organization spend alerts

# Organization users

# Project roles & role bindings

# Organization external storage

# Organization spend limit

# Project spend limit

# 3. Roles & scopes catalogue

Governance knobs documented in production-best-practices: max API-key lifetime (org and project, project ≤ org), API Key Governance (allow only service-account keys / only user keys / block new keys; org restrictions win), key usage tracking (keys created before 2023-12-20 are untracked by default).

# 4. Usage & costs query cookbook (ACCOUNT_RESTRICTED for us — verified 403 api.usage.read)

All usage endpoints share the same query grammar (from the OpenAPI spec):

Recipes (curl; -G turns --data-urlencode into query params):

# daily completions tokens per model for the last 7 days
curl -G https://api.openai.com/v1/organization/usage/completions -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  --data-urlencode "start_time=$(( $(date +%s) - 7*86400 ))" --data-urlencode bucket_width=1d \
  --data-urlencode group_by=model --data-urlencode group_by=service_tier --data-urlencode limit=7
# hourly usage of one project, Batch only, paginated
curl -G https://api.openai.com/v1/organization/usage/completions -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  --data-urlencode start_time=1789000000 --data-urlencode bucket_width=1h --data-urlencode project_ids=proj_XXX \
  --data-urlencode batch=true --data-urlencode limit=168 --data-urlencode page=page_AAAA…
# spend in USD per day per line item and project
curl -G https://api.openai.com/v1/organization/costs -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  --data-urlencode start_time=$(( $(date +%s) - 30*86400 )) --data-urlencode bucket_width=1d \
  --data-urlencode group_by=line_item --data-urlencode group_by=project_id --data-urlencode limit=31

Python: client.admin.organization.usage.completions(start_time=…, bucket_width="1d", group_by=["model"], limit=7); costs: client.admin.organization.usage.costs(...). Runnable examples: examples/openai/admin/usage_costs.sh, admin_readonly.py, admin_readonly.ts (all return 403 on our account).

# 5. Spend limits, alerts, data retention, permissions

# 6. Audit logs

GET /v1/organization/audit_logs (scope api.audit_logs.read; HTTP 401 not 403 without it). Filters: effective_at[gt|gte|lt|lte], project_ids[], event_types[], actor_ids[], actor_emails[], resource_ids[], limit, after, before. Each entry: {object:"organization.audit_log", id, type, effective_at, project{id,name}, actor{type: session|api_key, session{user, ip_address, user_agent, ja3, ja4, ip_address_details}, api_key{type: user|service_account, id, user|service_account}}, <type>: {payload}}.

Payload fields per event are in generated/fragments/audit-log-events/openai-audit-log-events.json (57 events carry a typed payload in the spec; the tenant.* enterprise-workspace events are enum-only).

# 7. Verified behaviour with a non-admin key (2026-09-18)

Response headers on these errors still include x-request-id, openai-version: 2020-10-01, openai-processing-ms, and (except certificates/audit logs) openai-organization / openai-project.

# 8. SDK access

from openai import OpenAI
client = OpenAI(admin_api_key=os.environ["OPENAI_ADMIN_KEY"])      # Python >= 2.34.0
users = client.admin.organization.users.list(limit=20)              # SyncConversationCursorPage -> iterate
for u in users: print(u.id, u.email, u.role)
client.admin.organization.projects.model_permissions.update("proj_abc", mode="allow_list", model_ids=["gpt-4.1"])

const client = new OpenAI({ adminAPIKey: process.env.OPENAI_ADMIN_KEY }); // Node >= 6.36.0
for await (const log of client.admin.organization.auditLogs.list({ limit: 50 })) console.log(log.type);

Go option.WithAdminAPIKey (≥ 3.34.0), Java OpenAIOkHttpClient.builder().adminApiKey(...) (≥ 4.34.0), Ruby OpenAI::Client.new(admin_api_key:) (≥ 0.61.0).