Secrets and credentials handling
Keep credentials out of prompts, docs, source examples, and committed configuration while still making setup verifiable.
What counts as a secret
A secret is any credential that grants access or proves identity.
- API keys, OAuth refresh tokens, bearer tokens, passwords, client secrets, database passwords, connection secrets, and deployment credentials are secrets.
- Provider names, model names, and non-sensitive preferences are not secrets.
- Never paste live credentials into public docs or source examples.
Safe storage
Store credentials in the system intended for secrets, not in memory prompts or wiki pages.
- Use secret storage for credential material.
- Use ontology memory for non-secret facts and preferences.
- Refer to stored credentials by logical key name in later work instead of repeating the raw value.
- Use safe example values in docs, samples, and support messages.
Safe request patterns
Good credential requests name the purpose, the logical key, and the safe reporting boundary without asking Buffaly to echo the value.
Store this provider API key as Provider.Example.ApiKey. Do not echo it back.
Check whether the provider credential exists. Report only whether it is configured.
Use the existing deployment credential key for staging. Do not print the credential.
If a credential appears in a prompt, document, wiki page, or source example by mistake, move it into the secret path, remove it from normal content, and rotate it when exposure risk is real.
Handling checklist
Use a repeatable checklist any time a setup task involves credentials.
- Identify the logical secret key name, intended integration, and whether the operation expects a key reference or the raw value.
- Store the value first, then refer to the stored secret by its key or label in follow-up work.
- Use the secret only for the active operation and report non-secret diagnostics if it fails.
- Before committing or sharing logs, scan the diff and output for copied keys, tokens, connection strings, or passwords.
- If a value was exposed, rotate it before treating the setup as complete.
Troubleshooting secret-related failures
When credentialed work fails, check the safe boundaries before retrying or asking the user to paste the value again.
| Layer | Safe check |
|---|---|
| Key name | Confirm the expected logical key name and current environment. |
| Secret presence | Report only whether the secret is configured, not the value. |
| Integration shape | Check whether the provider expects a key reference, raw value, token, password, or connection secret. |
| Target account | Confirm provider, account, deployment target, and environment before retrying. |
Validation
Validate credentials without exposing them.
- Run a small provider call or integration check.
- Report success/failure without echoing the credential.
- Rotate the credential if it appears in logs, commits, or chat history.