CI API Key Rotation

Use this runbook when the docs workflow reports that OILPRICE_API_KEY is missing, unauthorized, forbidden, or otherwise unable to preflight GET /v1/prices/latest.

The docs live-test key is stored as the GitHub Actions secret OILPRICE_API_KEY in OilpriceAPI/oilpriceapi-docs. GitHub secrets cannot be read back, so rotation always creates a new key and replaces the secret.

Create a Replacement Key

Use an existing active key for the docs CI account from the team secret manager. Do not paste keys into tickets, commit messages, shell history exports, or logs.

curl -sS -X POST "https://api.oilpriceapi.com/v1/api-keys" \
  -H "Authorization: Token EXISTING_ACTIVE_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"docs-live-tests-YYYY-MM-DD"}'

The response includes data.api_key.plain_token exactly once. Store that value directly into GitHub Actions.

Preflight the New Key

curl -sS -o /tmp/oilpriceapi-docs-key-preflight.json -w "%{http_code}\n" \
  -H "Authorization: Token NEW_DOCS_CI_KEY" \
  "https://api.oilpriceapi.com/v1/prices/latest"

Expected result: 200.

If the response is 401 or 403, do not update the GitHub secret. Create a new key from an active account key or check whether the account is suspended, over quota, or missing the required plan access.

Update GitHub Actions

gh secret set OILPRICE_API_KEY \
  --repo OilpriceAPI/oilpriceapi-docs \
  --body "NEW_DOCS_CI_KEY"

After updating the secret, clear local response files that may contain token material.

: > /tmp/oilpriceapi-docs-key-preflight.json

Verify the Workflow

gh workflow run docs-validation.yml \
  --repo OilpriceAPI/oilpriceapi-docs \
  --ref master

Watch the run and confirm all three jobs pass.

gh run watch RUN_ID \
  --repo OilpriceAPI/oilpriceapi-docs \
  --exit-status \
  --interval 10

The Live API Tests job must execute the production documentation examples. It should not exit from the missing-key or 401/403 preflight branches.

Cleanup

List keys for the account and revoke old docs/test keys after the replacement has passed.

curl -sS "https://api.oilpriceapi.com/v1/api-keys" \
  -H "Authorization: Token EXISTING_ACTIVE_ACCOUNT_KEY"

curl -sS -X DELETE "https://api.oilpriceapi.com/v1/api-keys/OLD_KEY_ID" \
  -H "Authorization: Token EXISTING_ACTIVE_ACCOUNT_KEY"

Keep at least one active management key on the account. The API will reject revoking the last active key.

Canonical Endpoints