generated: '2026-07-18'
method: searched
source: >-
  https://docs.castle.io/docs/integration-guide,
  https://docs.castle.io/docs/webhooks,
  https://docs.castle.io/docs/api-custom-parameters,
  https://castle.io/pricing
description: >-
  Cross-cutting request/response conventions for the Castle REST API: how
  authentication, the client-side request token, event typing, rate limiting,
  versioning, and webhook signing behave across every operation.
base_url: https://api.castle.io
api_style: REST over HTTPS, JSON request and response bodies
authentication:
  scheme: HTTP Basic (API Secret as password, empty username)
  docs: https://docs.castle.io/docs/integration-guide
  detail: authentication/castle-authentication.yml
request_token:
  supported: true
  mechanism: >-
    A client-side request token is generated by the browser SDK
    (castle.createRequestToken()) or the mobile SDK and passed to the backend on
    each Risk/Filter call as `request_token`.
  ttl_seconds: 120
  single_use: true
  note: >-
    The token is an anonymous device fingerprint that must be refreshed on every
    backend call; it expires after 120 seconds.
event_model:
  types:
  - "$registration"
  - "$login"
  - "$profile_update"
  - "$transaction"
  - "$password_reset"
  - "$challenge"
  - "$custom"
  statuses:
  - "$attempted"
  - "$succeeded"
  - "$failed"
  apis:
    risk: Authenticated users (after login/registration succeeds) — POST /v1/risk
    filter: Anonymous users (before login/registration succeeds) — POST /v1/filter
    log: Record an event without scoring — POST /v1/log
  custom_parameters:
    supported: true
    docs: https://docs.castle.io/docs/api-custom-parameters
idempotency:
  supported: false
  note: >-
    Castle does not document an idempotency-key header. Scoring calls are
    designed to be sent per-event with a single-use request_token; the platform
    deduplicates at the event level rather than via a client-supplied key.
pagination:
  style: not-documented
  note: Events API query/group use results_size + page fields for enterprise queries.
versioning:
  scheme: uri-path
  current: v1
  api_version_field: >-
    Webhook payloads and event responses carry an `api_version` field.
error_envelope:
  format: json
  detail: errors/castle-problem-types.yml
rate_limiting:
  documented: true
  source: https://castle.io/pricing
  signal: Enforced per plan (Pro tier documents 5 API requests/second); 429 on exhaustion.
webhooks:
  supported: true
  signature_header: X-Castle-Signature
  signature_algorithm: HMAC-SHA256 over the raw JSON body keyed with the API Secret
  detail: asyncapi/castle-webhooks.yml