Secrets and credential rotation

FastHook uses several unrelated secret classes. Rotate the exposed class only, update every consumer, and verify one controlled event before revoking the previous provider credential. Never reuse a project API key as a webhook secret or a provider token as a FastHook signing secret.

Secret inventory

| Secret class | Purpose | Where it is used | Rotation effect | | --- | --- | --- | --- | | Project API key | Authenticate Control API, CLI, and compatible machine clients for one team | Authorization: Bearer ... or x-api-key | The previous key stops authenticating after replacement. | | Project signing secret | Sign outbound FastHook deliveries using FASTHOOK_SIGNATURE | Receiver-side signature verification | Receivers using the previous secret reject new signatures after rotation. | | Connected provider credential | Authorize Triggers, subscriptions, resource lookups, and Actions | OAuth, app installation, API-key, or service-specific account connection | Reconnect or credential replacement can affect every Source and Action using that account. | | Source authentication secret | Verify inbound webhook senders | Source auth configuration and provider signature headers | The provider and Source must agree during cutover. | | Destination or Action credential | Authenticate an outbound call | Destination configuration or provider account | Delivery can fail immediately if the receiver has not accepted the new value. | | Sanitized share token | Read one expiring request snapshot | Public share URL | It expires according to its TTL; treat the URL itself as a bearer credential. |

Keep a private inventory with the team, environment, resource ID, owner, last rotation time, and all known consumers. Do not put secret values in the inventory.

Connected provider credentials

Provider accounts store usable credential material in authenticated encrypted envelopes. The current backend uses AES-GCM with a random 12-byte IV and supports key identifiers so operators can rewrap stored credentials during encryption-key rotation. Ordinary connected-account responses expose lifecycle and metadata, not the credential value.

This protection does not make broad account access safe. A connected account can be reused by multiple Triggers and Actions in the same team, so one reconnection, revocation, scope change, or provider-side role change can affect several Workflows.

For OAuth and app installations:

1. identify every Source and Action using the account;
2. pause Workflows where failed or repeated side effects would be unsafe;
3. reconnect from the affected Trigger or Action so current scope requirements are included;
4. confirm the account lifecycle returns to active;
5. reload remote resource selectors; and
6. execute one controlled event and inspect Audit and the provider result.

For API credentials, create the replacement at the provider, save it in the correct FastHook connected account, test it, and only then revoke the previous provider credential.

Project API key and signing secret

The project-secret response contains both complete values as well as masked values and last-rotation timestamps. Therefore, treat GET /v1/project-secrets and any captured response as highly sensitive. Team membership is currently enough for a dashboard session to reach protected team resources; do not assume a read-only member cannot retrieve project secrets.

The two values are independent:

• the API key authenticates a caller to FastHook; and
• the signing secret lets a receiver verify outbound FastHook delivery signatures.

POST /v1/project-secrets/rotate rotates both values when rotate is omitted. Pass {"rotate":["api_key"]} or {"rotate":["signing_secret"]} to rotate only one class. PUT /v1/project-secrets accepts a caller-supplied api_key, signing_secret, or both; each supplied value must be at least 12 characters.

Rotate the project API key

1. Inventory every API, CLI, MCP, tunnel, script, and secret-manager entry that uses the current key.
2. Pause automated configuration changes when partial cutover would be unsafe.
3. Authenticate one rotation request with the current key and capture the returned new value directly into an approved secret store.
4. Update all callers immediately. Keep x-team-id aligned with the key’s team.
5. Verify /v1/auth/me or one harmless list operation from every caller.
6. Remove the previous value from local files, CI variables, shell history, and temporary incident notes.

There is one active project API key per team in the current model, not a set of independently revocable client keys. Coordinate the cutover accordingly.

Rotate the project signing secret

1. Inventory every receiver that verifies FASTHOOK_SIGNATURE.
2. If receivers support dual-secret verification, deploy the new secret as an additional accepted value first.
3. Rotate only signing_secret in FastHook.
4. Send one controlled delivery and verify the signature with the new secret.
5. Remove the old receiver secret after the cutover window.

If a receiver accepts only one secret, plan a short coordinated change window. Do not rotate the API key merely because the signing secret changed.

Rotate inbound Source secrets

Inbound signature or API-key validation is configured per Source. The provider and FastHook must use matching material, and some providers control whether two secrets can overlap.

1. Confirm the Source type, auth_type, expected signature header, and provider account.
2. Pause downstream side effects when failed verification could lose important events.
3. Add or generate the new provider-side secret according to the provider’s overlap rules.
4. Update the FastHook Source configuration.
5. Send a signed test event and confirm it is verified and routed once.
6. retire the previous provider secret; and
7. inspect rejected requests for source_auth_failed after cutover.

Use the relevant Source type reference for exact headers and validation input.

Exposure response

If a secret may have leaked:

1. identify its class before rotating anything;
2. remove the value from public pages, screenshots, fixtures, mappings, logs, and tickets;
3. rotate or revoke it at the authoritative system;
4. update consumers and run a controlled verification;
5. inspect FastHook Audit, request history, and provider logs for use during the exposure window; and
6. record the affected resources and response timeline without copying the secret into the incident report.

Audit and sanitized sharing redact many sensitive key names, but redaction is a safety layer, not permission to place credentials in payloads. Continue with Data handling and retention and Security and governance.