Secrets management in OpenAPI files

Why secrets leak

A credential copied into an example can travel from a private repository into generated documentation, a collection export, and a public search index. Anyone who can read the file may be able to use the key until it is revoked. Review examples and supporting files as part of the same release process as the API contract.

Where to look

• Example headers (Authorization: Bearer <token>) embedded in specs.
• Server URLs that include basic auth.
• Postman environment exports with real keys.
• Inline secrets inside webhook callback examples.

Safe patterns

• Use placeholders like YOUR_API_KEY and document how to create keys.
• Store real credentials in vaults; inject via environment variables in CI.
• Separate public docs from internal specs; strip examples before publishing.
• Rotate keys automatically when a leak is detected.

Use a dedicated secret scanner on every commit and before publishing docs. APISAST's OpenAPI security scanner checks design signals such as credentials in URL parameters; it is not a general secret detector for example values.

Trace how an example reaches readers

An OpenAPI file can be copied into a docs site, SDK repository, support ticket, or API collection. Map that path for your service and decide which version is safe to publish. Use synthetic account IDs and placeholder tokens in examples, and keep test credentials separate from production credentials. A token that looks harmless in a development file may still work against an internal environment if it was generated from a shared account.

Review request headers, query examples, server URLs, callback URLs, and prose descriptions. A basic-auth username in a URL can leak through logs or browser history. For authentication documentation, show the scheme and the steps to obtain a credential; do not embed a usable key. Keep private environment variables out of collection exports before sharing them with partners.

Build a safer publishing pipeline

Run secret scanning on the specification, generated docs, example files, and collection exports. Test known patterns and allow approved placeholders so false positives do not drown out real leaks. Give a reviewer a way to inspect new examples before publication. If a docs generator inserts live values from an environment, separate that environment from production and verify the final built site, not only the source file.

Keep the pipeline's real credentials in a secret store and pass them only to steps that need them. Avoid printing values in CI logs or build artifacts. A pull-request job from an untrusted fork should not receive production secrets. The CI/CD scanning guide shows how to review a contract separately from the implementation tests.

Respond to a leaked credential

First identify the credential's scope, owner, and last known use. Revoke or rotate it promptly; deleting the file does not remove copies from clones, caches, or generated documentation. Search the repository history and distribution channels to understand where it travelled. Review access logs for misuse and notify the affected service owner. Record the incident without pasting the leaked value into a public issue.

After rotation, replace examples with placeholders and add a regression check for the pattern that escaped. Verify that clients have a safe migration path if a shared key must change. A secret scanner helps detect literal credentials; an OpenAPI design scan helps spot unsafe credential placement. Use both where relevant and verify that a revoked key no longer works.

Incident response

If a credential leaks, revoke it, rotate downstream secrets, and add regression tests so the same pattern cannot merge again. Notify affected partners and update audit logs. Keep a playbook in the repo so engineers know the exact steps.

For a shared credential, list every consumer before rotation and give each one a replacement through a secure channel. Prefer moving them to separate credentials so a later compromise has a smaller blast radius. Search generated documentation and cached exports as well as the repository; removing the source line does not erase every published copy. Verify the old credential fails, review access logs for unexpected use, and keep the remediation record free of the secret value itself.

A useful playbook states who can revoke a key, who contacts affected integrators, and how the team confirms recovery. Exercise it with a test credential so the first run is not during an incident.