Proposal: Collection-scoped API keys for AI agent vault access

[tamirdresher]

PR Proposal

PR: bitwarden/server#7261
Feature Request: bitwarden/server#7252
Jira: PM-33910

Problem

AI agent teams need credential storage with server-enforced isolation. Today, Bitwarden Organizations have Collections, but there's no way to issue an API key scoped to a single Collection. This means agents either get full org access (too broad) or need a separate account per agent (unmanageable).

Proposed Solution

Add collection-scoped API keys — a new API key type that grants access only to items within a specific collection. This reuses the existing SecretsManager ApiKey pattern and adds:

1. Data model: OrganizationId + CollectionId columns on the ApiKey entity
2. Auth: New vault_api_key grant type with VaultApiKeyGrantValidator — authenticates via client_id/client_secret, emits collection_id JWT claim
3. API: CollectionApiKeysController with Create/List/Revoke endpoints at /organizations/{orgId}/collections/{collectionId}/api-keys
4. Filtering: CiphersController and SyncController enforce collection scope from JWT claims
5. Tests: 20 unit tests covering auth, command, and filtering

Use Case

Teams running multiple AI agents (CI bots, deployment scripts, monitoring tools) can:

• Create one Collection per agent/team
• Issue a scoped API key for each
• Agent can only read/write items in its collection — server-enforced, not client-trust

Implementation Status

PR is complete with all tests passing. CLA signed. Ready for review.

[github-actions[bot]]

✨ Thank you for your code contribution proposal! While the Bitwarden team reviews your submission, we encourage you to check out our contribution guidelines.

Please ensure that your code contribution includes a detailed description of what you would like to contribute, along with any relevant screenshots and links to existing feature requests. This information helps us gather feedback from the community and Bitwarden team members before you start writing code.

To keep discussions focused, posts that do not include a proposal for a code contribution will be removed.

• 💡 For feature requests and general discussion, please visit the Bitwarden Community Forums.
• ℹ️ For questions and support, visit the Bitwarden Help Center.
• 🐛 To report a potential bug, please visit the corresponding repo. Server | Clients | iOS | Android

Thank you for contributing to Bitwarden!