Agent credentials scoped per project
Project-scoped agent credentials means that each project has its own dedicated set of credentials that agents use when working on that project, rather than agents inheriting the de
- ·Dedicated development environments exist for agent execution (separate from developer's primary workspace)
- ·Basic sandboxing via Docker or equivalent containers is implemented
- ·Agent credentials are scoped per project (not a single org-wide key)
- ·Container images for agent environments are versioned and reproducible
- ·Credential rotation schedule exists for agent-scoped keys
Evidence
- ·Docker or container configuration files for agent environments
- ·Credential management configuration showing per-project scoping
- ·Environment provisioning documentation or scripts
What It Is
Project-scoped agent credentials means that each project has its own dedicated set of credentials that agents use when working on that project, rather than agents inheriting the developer's personal credentials. Instead of the agent accessing GitHub with your personal token that has permissions across the entire organization, it uses a bot token scoped to the specific repository. Instead of accessing AWS with an IAM user that can read all S3 buckets, it uses a role that can only access the specific buckets the project needs.
This is the first implementation of least-privilege access for agents. It does not require containerization or cloud dev environments - project-scoped credentials can be implemented today in any environment by creating dedicated service account tokens and storing them separately from developer credentials. The mechanism is simple: create a credential, scope it to the minimum necessary permissions, store it in a project-specific .env.agent file or a secrets manager key, and configure the agent to use that credential rather than inheriting from the shell environment.
Project-scoped credentials provide two distinct benefits. The security benefit is containment: if an agent misbehaves or is compromised, the damage is limited to what the project credential can do. The audit benefit is attribution: when you look at audit logs for GitHub, AWS, or Jira, you can distinguish between actions taken by the developer and actions taken by the agent, because they use different credentials with different identities.
The practical challenge is credential management overhead. Creating and rotating scoped credentials for every project is more work than using personal credentials. This overhead is real but manageable with the right tooling. HashiCorp Vault's dynamic secrets (which generate short-lived, scoped credentials on demand) and GitHub Apps (which provide repository-scoped tokens without creating service accounts) are the tools that make project-scoped credentials operationally sustainable.
Why It Matters
- Blast radius containment - a project-scoped credential that is compromised or misused can only affect resources within that project's scope, not the entire organization's infrastructure
- Audit log attribution - operations performed by agent credentials appear in audit logs with a distinct identity, making it possible to reconstruct what an agent did independently of what the developer did
- Compliance alignment - service accounts with documented scopes are the standard access model for compliance frameworks; project-scoped agent credentials fit naturally into SOC 2 and ISO 27001 access review processes
- Rotation without developer disruption - project credentials can be rotated without touching the developer's personal credentials, simplifying the rotation process and enabling more frequent rotation
- Enables multi-project agent workflows - when each project has distinct credentials, agents that work across project boundaries make explicit, auditable cross-project accesses rather than silently inheriting broad access
Getting Started
- Inventory existing agent credential usage - For each project where agents are in use, document which credentials the agent currently uses (GitHub token, AWS credentials, Jira token, etc.) and what permissions those credentials have. This inventory is the starting point for scoping down.
- Create a GitHub App per repository - GitHub Apps are the right mechanism for repository-scoped agent access. Create an app with access to a specific repository, generate an installation token for that app, and configure the agent to use it. GitHub App tokens are automatically scoped to the repositories the app is installed on and expire after one hour.
- Create IAM roles with resource-based policies - For AWS access, create a dedicated IAM role for each project with policies that name specific resources (S3 bucket ARNs, DynamoDB table ARNs) rather than using wildcards. Agents assume the role for the project they are working on, not a shared broad-access role.
- Store project credentials in a dedicated location - Use a pattern like
.env.agent(gitignored) or a secrets manager path (/projects/{project-name}/agent/) to store project credentials separately from developer credentials. Never store agent credentials in the developer's shell profile or global credential files. - Configure the agent to use project credentials - For Claude Code, set environment variables before the session that point to project-specific credentials. For CI-based agents, inject credentials from the secrets manager at job start. Verify that the developer's personal credentials are not accessible in the agent's environment.
- Set up credential rotation - Project credentials should rotate at least quarterly, preferably monthly. Use HashiCorp Vault dynamic secrets or GitHub App token expiry (1 hour by default) to automate rotation. Document the rotation process so it is not a manual, error-prone step.
Use GitHub Apps instead of personal access tokens for repository access. A GitHub App token is automatically scoped to the repositories the app is installed on, expires after one hour, and can be revoked instantly. This makes it far safer than a long-lived personal access token with org-level permissions.
Common Pitfalls
Creating project credentials that are still too broad. A GitHub token for "project A" that has read/write access to all repositories in the organization is not actually project-scoped - it just has a different name. The credential scope must match the actual resource scope. Review the specific permission scopes of each credential rather than trusting the name to reflect the scope.
Storing project credentials in the repository. .env.agent files should be in .gitignore and never committed. Project credentials in a committed file expose them to everyone with repository read access and make rotation require a git history rewrite. Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, GitHub Secrets) for storage, not the filesystem.
Not rotating credentials after a developer leaves. Project credentials that were used by a developer who has left the organization should be rotated immediately, even if they are scoped to a specific project. Former employees retain access to any credential they knew, regardless of their employment status.
Forgetting about transitive credential access. A project credential that can read from a database might be able to read data that belongs to other projects stored in the same database. Scoping credentials to a project does not automatically scope them to project-specific data within shared resources. Review the data boundaries, not just the resource boundaries.
No audit of what project credentials can actually do. After creating scoped credentials, verify their scope by testing what they can and cannot access. A credential that you intend to have repository-read-only access should fail if you try to push with it or create a PR. Test the negative cases, not just the positive ones.
How Different Roles See It
Bob's team uses personal developer tokens for all agent operations. A developer recently left the team, and Bob realized he had no way to know which systems might still have that developer's credentials stored in agent configurations. He asked three other developers to audit their agent setups and found credentials in .env files, shell profiles, and IDE settings - with no consistent pattern.
What Bob should do: Bob should treat credential hygiene as a sprint-level commitment, not a background task. He should allocate one sprint where every developer audits their agent credential setup and migrates to project-scoped credentials stored in the team's secrets manager. Bob should create a template: for each project, here are the credentials you need, here is how to create them with the right scope, here is where to store them. The sprint ends with a checklist audit: every project has documented, scoped credentials, and no project uses personal developer credentials for agent operations. This one-time investment pays dividends every time a developer rotates off the team.
Sarah has been involved in a security audit and the auditors asked about AI agent access controls. She could not answer how agent credentials were scoped, what they had access to, or how they were rotated. The audit revealed that the team's AI tooling is a gap in their access management practices. Sarah needs to close that gap without creating so much overhead that developers stop using agents.
What Sarah should do: Sarah should design the credential management workflow to minimize developer friction. The ideal state is: agent credentials are provisioned automatically when a developer starts working on a project, they are scoped correctly by default, and they rotate automatically without developer action. This requires tooling investment (Vault dynamic secrets or a custom credential provisioning script) but it pays off in compliance auditability and reduced manual work. Sarah should partner with the security team to define what "correctly scoped" means for each type of credential, and then implement tooling that makes correct scoping the default rather than a choice each developer makes independently.
Victor has built a credential management system for his own projects that he is proud of: each project has a .env.agent file with project-specific credentials, all stored in 1Password and rotated monthly. But it is a manual system that he manages himself. When he looks at the rest of the team, he sees ad-hoc personal credentials everywhere.
What Victor should do: Victor should build a credential provisioning CLI that automates what he does manually. The tool takes a project name as input, creates the appropriate scoped credentials in GitHub, AWS, and other systems, stores them in the team's secrets manager, and writes a .env.agent file to the project directory. Running agent-creds provision --project myapp should be a 30-second operation that any developer can run. Victor should also add credential validation to the CI pipeline: if an agent task runs in CI with credentials that have broader scope than the project requires, the CI job emits a warning. This combination of tooling and automated validation creates the credential discipline the team needs without requiring each developer to think through credential scoping from scratch.
Further Reading
From the Field
Recent releases, projects, and discussions relevant to this maturity level.
Where does your team actually sit on this?
This guide describes one level of one area. Run the assessment to place your team across all 16 areas, see which gates you have passed, and get a report you can take to your stakeholders.
Agent Runtime & Sandboxing