Securing API Keys

An API key names a workspace and a project. Anything holding it can install through the proxy as that project, so the practices below are mostly about keeping it in one place and making it cheap to replace.

Keep keys out of source control

Use environment variables or a secret manager, and commit only configuration that references them. Every ecosystem page shows the committable form.

The files that tend to end up carrying a literal key:

• .npmrc with _authToken set to the key rather than ${SHIELDEDSTACK_API_KEY}
• nuget.config with ClearTextPassword
• pip.conf and pip.ini, where the credential is inside the index URL
• .bundle/config, when Bundler credentials were set without --global
• Cargo’s credentials.toml
• .env files of every description

Keep credential-bearing local files out of source control before the first commit. Some files, such as .npmrc, can be committed safely when they contain only environment-variable references; do not ignore the safe template just because a local copy could contain a literal key. Follow the relevant ecosystem guide for the committable form.

Rotate deliberately

Create the new key, roll it out, then revoke the old one. Because several keys can share a project name, rotation does not interrupt tracking or split a project’s history.

Revoking a key does not delete data. Historical usage stays attributed to the project.

If a key is exposed, revoke it immediately rather than waiting for a planned rotation. Replace it where needed, then review request logs for unexpected activity under the affected project. Project attribution may include activity from other keys for that project; the logs are not proof that a particular key was used.

Scope keys so revocation is cheap

Separate keys per environment, project, or pipeline so a leaked key can be revoked without stopping everyone else’s builds. Use distinct project names when you need request logs to distinguish those workloads; separate keys under one project share its attribution.

These separate keys make attribution and revocation easier; a project name is not a permission boundary. Enable Allow read-only workspace data access only when a key needs MCP access. That capability exposes data across the key’s workspace, not just the named project, so use a dedicated key for it.

Protect keys in CI

Use the platform’s secret store: GitHub Secrets, Azure Key Vault, AWS Secrets Manager, or your own vault. Inject the key only into the steps that need it. Masking helps, but do not print the key or an effective package-manager URL: credentials embedded in URLs or transformed by a client may not be masked. See CI/CD integration for setup guidance.

Review periodically

• Audit who holds keys, and revoke unused ones.
• Watch the Portal for alerts on packages you already have.
• Re-read the workspace’s package filters, since a rule added during an incident often outlives its reason.