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 | | --- | --- | --- | --- | | Scoped project API key | Authenticate Control API, CLI, and compatible machine clients for one team | Authorization: Bearer ... or x-api-key | Each key has its own scopes, execution grants, rate limit, lifecycle, and audit trail. | | 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

New automation should use independently revocable keys from /v1/project-api-keys. A project owner can create multiple named keys, assign control:read, control:edit, and control:execute scopes, restrict execute access with resource grants, and set a per-minute rate limit. The raw credential is returned exactly once by POST /v1/project-api-keys; list and detail responses return masked metadata only. Use DELETE /v1/project-api-keys/{keyId} or its /revoke alias for permanent revocation, and inspect /audit for recent authorization decisions.

GET /v1/project-secrets remains the compatibility surface for the legacy team API credential and the project signing secret. It returns masked values, has_secret, and last-rotation timestamps, never reusable values. A project owner can rotate either legacy value; the replacement is returned only in that successful rotation response, so copy it directly into an approved secret store.

The two values are independent:

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. Both mutation endpoints require an owner dashboard session (site administrators are also permitted); project API keys and non-owner sessions cannot mutate this trust root.

Create or revoke a scoped project API key

  1. Choose the minimum scopes and execution grants required by the caller.
  2. Create a named key with an owner dashboard session and capture the one-time data.api_key value directly into an approved secret store.
  3. Verify one harmless operation, then inspect the key's audit endpoint for the decision.
  4. Revoke the individual key when the caller is retired or the credential may have leaked.

Rotate the legacy 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 an owner dashboard session 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.

Legacy rotation replaces the compatibility credential for the whole team. It does not rotate, revoke, or otherwise change scoped keys created through /v1/project-api-keys.

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.