Coffrifydocs
⌘K
All docs
API · OpenAPI 3.1 · v1.0.0

Coffrify Public API

Encrypted file transfers as a service — for developers.

API version2026-05-14
AuthAuthorization: Bearer cof_live_…
Rate limit headersX-RateLimit-Limit / Remaining / Reset / Policy
IdempotencyIdempotency-Key: <your-uuid>
Request tracingX-Request-Id (echo+inbound)
VersioningX-Coffrify-Api-Version on every response

Meta

Welcome + identity endpoints.

GET/v1/welcomePublic welcome message + API metadata.
GET/v1/meResolve the API key into its workspace, scopes and user.

Transfers

Create, list, inspect and revoke transfers.

GET/v1/transfersList transfers in the workspace.
POST/v1/transfersCreate a transfer (returns a presigned upload token).
GET/v1/transfers/{id}Fetch a transfer by ID.
DELETE/v1/transfers/{id}Revoke a transfer (delete files).

API keys

Manage your API keys (scopes, rotation, revocation).

GET/v1/api-keysList API keys for the workspace.
POST/v1/api-keysCreate a new API key. Returns the raw key ONCE.
PATCH/v1/api-keys/{id}Update name / IP allowlist / max_uses on a key.
DELETE/v1/api-keys/{id}Revoke a key. Fires `api_key.revoked`.
POST/v1/api-keys/{id}/rotateRotate a key — new value + grace period for the old one.

Webhooks

Subscribe to events. 43+ event types in the catalog.

GET/v1/webhooksList webhooks.
POST/v1/webhooksCreate a webhook. Returns the signing secret ONCE.
PATCH/v1/webhooksUpdate a webhook.
DELETE/v1/webhooksDelete a webhook.
GET/v1/webhooks/eventsList the event catalog (event types + payload shape).
GET/v1/webhooks/{id}/deliveriesList delivery attempts for a webhook (debug).

Audit

Read the workspace audit log.

GET/v1/auditQuery the workspace audit log.

Webhook conventions

Coffrify webhooks are Standard Webhooks-compatible (standardwebhooks.com). We emit BOTH the new spec headers and the legacy X-Coffrify-Signature for back-compat.

{
  "signing": {
    "standard_compliant": true,
    "spec": "https://www.standardwebhooks.com/",
    "headers_emitted": [
      "webhook-id (uuid — stable across retries; use for idempotency)",
      "webhook-timestamp (unix seconds)",
      "webhook-signature (`v1,<base64-hmac-sha256>` — multi-sig space-separated during rotation)",
      "X-Coffrify-Signature (legacy `t=<ts>,v1=<hex>` format — kept for back-compat)",
      "X-Coffrify-Event-Id, X-Coffrify-Event-Type (legacy headers)",
      "X-Coffrify-Test-Delivery: true (only on /v1/webhooks/{id}/test deliveries)"
    ],
    "idempotency": "Receivers should dedupe on `webhook-id`. The same id is used across all retries AND replays."
  },
  "replay": {
    "endpoint": "POST /v1/webhooks/{id}/test (action=replay via dashboard) — preserves the original event_id.",
    "marker": "Replay deliveries set `original_delivery_id` in the database and ship the same `webhook-id` header."
  },
  "rotation": {
    "endpoint": "POST /v1/webhooks/{id}/rotate-secret",
    "grace_window_default_hours": 24,
    "grace_window_max_hours": 168,
    "behavior": "Both the new and previous secrets validate during the grace window. Plan your rollover; after the window closes, only the new secret works."
  },
  "retry_policy": {
    "default_max_attempts": 10,
    "default_disable_after_consecutive_failures": 50,
    "override": "Set `retry_policy.disable_after_consecutive_failures` per webhook (1–10000).",
    "backoff_seconds": [
      60,
      300,
      1800,
      7200,
      21600,
      43200,
      86400,
      86400,
      86400
    ]
  },
  "sandbox": {
    "endpoint": "POST /v1/webhooks/{id}/test",
    "accepts": {
      "id": "uuid (required)",
      "event_type": "any catalog entry or 'ping' (default)",
      "data": "optional custom payload"
    }
  }
}