> For the complete documentation index, see [llms.txt](https://handbook.harmonic.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://handbook.harmonic.security/handbook/1.-identity-and-access/1.6-api-keys-and-service-accounts-governance.md). # 1.6 API keys and service accounts governance How to keep personal keys out of automation and scope, rotate, monitor, and attribute machine access properly. *Last reviewed: August 18, 2026* {% hint style="info" %} API keys are production credentials, even when they start as developer convenience. Treat them like secrets with owners, scope, rotation, monitoring, and a retirement path. {% endhint %} ## API keys and service accounts governance: what security teams need to know AI API keys often appear before a formal platform team exists. A developer builds a proof of concept, stores a key in a local environment file, pushes a prototype into CI, and then the prototype becomes useful. That path is common, but it creates a hard cleanup problem once the application handles company data. API access needs the same governance as other machine access. Keys should be tied to a project, service account, workload, or owner. They should be stored in a secret manager, kept out of source control and prompts, rotated on a schedule, and monitored for usage that does not match the application. Service accounts improve this when they are scoped correctly. A service account for one workload in one environment is easier to review than a personal key shared across several systems. Workload identity federation improves it further by replacing long-lived secrets with short-lived tokens based on an external identity. ## Common API keys and service accounts governance security failures * A personal API key runs production traffic. * One key is reused across development, staging, production, CI, and local scripts. * Keys are stored in code, notebooks, ticket comments, prompt history, shell history, or analytics logs. * A key remains active after the developer leaves or the proof of concept is retired. * Usage monitoring is enabled, but no one reviews it. * API organization settings and ChatGPT workspace settings are reviewed by different teams. ## API keys and service accounts governance security controls checklist * Create separate projects for production, staging, test, and experimentation. * Use service accounts or workload identity mappings for automation where supported. * Keep personal keys out of shared services, CI, scheduled jobs, and production systems. * Store keys in a managed secret store and inject them at runtime. * Rotate long-lived keys and tokens on a documented schedule. * Record owner, system, environment, data class, key scope, creation date, rotation date, and review date. * Monitor usage by key, project, model, and environment where the platform exposes it. * Revoke keys when owners leave, systems retire, scope changes, or suspicious usage appears. * Add secret scanning to repositories, CI logs, and prompt/tool telemetry where feasible. ## Anthropic ### Overview Anthropic's Claude Console role documentation separates several access levels. Both the Limited Developer and Developer roles can manage API keys and webhook endpoints, with Developer additionally able to view session traces and download files, while User and Claude Code User roles have narrower access. That makes API key administration part of role design as well as developer workflow. Console workspaces add a scoping layer: workspace roles can grant additional permissions over organization-level baselines, so record which workspace each key belongs to and verify exact key-scoping behavior against current Console documentation. Claude Code can authenticate through environment variables such as `ANTHROPIC_API_KEY`, bearer tokens, dynamic helper scripts, OAuth tokens, and cloud provider credentials. The documentation says `apiKeyHelper` can return dynamic or rotating credentials, which gives teams a path to vault-backed or short-lived credential patterns. For local developer machines, include environment variables and helper scripts in reviews. A managed web account does not prove the CLI is using the intended credential. Claude Tag channel sessions use service accounts provisioned by an owner. Credentials live in a separate store and Agent Proxy injects them only when a request matches an approved host or path; the model and sandbox do not receive the stored secret. Use a dedicated account per connected service, scope each credential to the smallest channel set, host set, path prefix, and HTTP methods, and keep direct-message activity separate because it runs under the user's own account. ### Anthropic documentation * [Claude Console roles and permissions](https://support.claude.com/en/articles/10186004-claude-console-roles-and-permissions) * [Claude Code authentication](https://code.claude.com/docs/en/team) * [Claude Code security](https://code.claude.com/docs/en/security) * [How Claude Tag agent identity works](https://claude.com/docs/claude-tag/concepts/agent-identity) * [Claude Tag security and data handling](https://claude.com/docs/claude-tag/concepts/security-and-data) ## OpenAI ### Overview OpenAI's production guidance says API keys authenticate API requests and should not be exposed in code or public repositories. It recommends environment variables or a secret management service. It also notes that API key usage can be monitored when tracking is enabled. OpenAI also documents workload identity federation. A trusted workload can exchange an external identity token for a short-lived OpenAI access token. Service account mappings can restrict which external identity can mint a token for a specific OpenAI service account, and mappings can further narrow permissions. For Codex, the Compliance API covers ChatGPT-authenticated Codex activity only. API-key-authenticated Codex runs follow API organization settings and do not appear in Compliance API exports. Include that difference in audit and investigation planning. ### OpenAI documentation * [Production best practices](https://developers.openai.com/api/docs/guides/production-best-practices) * [Workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation) * [Codex Governance](https://developers.openai.com/codex/enterprise/governance) ### Applicable Harmonic guides for OpenAI * [Securing Codex Best Practice](https://www.harmonic.security/resources/securing-codex-best-practice) ## Frequently asked questions about API keys and service accounts governance ### Should developers be allowed to create API keys? Yes for approved experimentation, but not without boundaries. Require separate projects, spend limits, owner records, and a path to move production traffic to service accounts or workload identity. ### How often should keys be rotated? Set a baseline rotation period, then rotate immediately when an owner leaves, a repository leak is suspected, an application changes hands, or usage looks wrong. Short-lived tokens reduce the need for manual rotation. ### What should a key inventory include? Include key or token type, owner, service, environment, project, allowed data class, storage location, creation date, last rotation date, last seen date, and decommission date. ### Are API keys safe to use in AI agent workflows? They can be safe when scoped, stored in a secret manager, monitored, and tied to a clear owner. Long-lived personal keys are a poor fit for production agents. ### When should workload identity replace API keys? Use workload identity for production automation when the platform supports it and the workload already has a trusted external identity, such as cloud infrastructure, CI, or Kubernetes. ## Applicable regulations and frameworks | Governance page | Relationship to this article | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | G.1 Map your controls to NIST AI RMF and CSF 2.0 | This article supplies implementation evidence for the NIST AI RMF and matching NIST CSF 2.0 outcomes. | | G.3 DORA and AI resilience in financial services | Conditional: for a DORA-regulated workflow, this supports identity and access control. | | G.5 SANS Critical AI Security Guidelines mapping | This article implements relevant SANS Access Controls guidance. | | G.6 Write an AI Acceptable Use Policy that holds up | This article supplies a technical or process control used to enforce the acceptable-use policy. | | G.7 Ownership and RACI for AI security | This control depends on the ownership and evidence responsibilities defined in the RACI. | | G.9 HIPAA controls for AI systems handling PHI | Conditional: for a workflow handling ePHI, this supports HIPAA identity, authentication, least privilege, and workforce access. | *G.2, G.3, G.4, and G.9 are conditional mappings. They apply only when the deployment is within the legal or regulatory scope described on the linked governance page.* ## Related handbook guidance * [1. Identity & Access](/handbook/1.-identity-and-access.md) * [1.5 Agent and non-human identity](/handbook/1.-identity-and-access/1.5-agent-and-non-human-identity.md) * [4.7 Secrets and credential hygiene in prompts and tools](/handbook/4.-data-protection-and-residency/4.7-secrets-and-credential-hygiene-in-prompts-and-tools.md) * [2.1 Connectors and apps: the integration backbone](/handbook/2.-supply-chain-and-extensibility/2.1-connectors-and-apps-the-integration-backbone.md) * [6.6 Evidence by surface and investigation paths](/handbook/6.-observability-audit-and-evidence/6.6-evidence-by-surface-and-investigation-paths.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://handbook.harmonic.security/handbook/1.-identity-and-access/1.6-api-keys-and-service-accounts-governance.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.