Authentication & Authorization

1. Authentication Models

ResultFly exposes two authentication models:

• Server-to-Server (API keys). Used by backend systems, integrations, and administrative tooling to configure campaigns or send events.
• User Context (JWT). Used by client apps (web, mobile, kiosk) to represent a specific participant while interacting with runtime APIs.

Both models rely on HTTPS and standard Authorization headers; ResultFly rejects unsigned or anonymous calls.

2. API Keys (S2S)

• Issuance. API keys are issued per tenant/integration through the ResultFly console or onboarding process. Keys identify the project and carry campaign scopes.
• Usage. Include the key in each request as Authorization: Bearer <api_key>. Rotate keys periodically and store them only on secure servers.
• Access scope. Keys are scoped to campaigns or global operations (for example, variable definition, external events). A key only authorizes actions explicitly granted during issuance; attempts to access other campaigns return 403 Forbidden.

3. User Tokens (JWT)

• Issuer. Tokens are minted either by the client’s identity provider (client-managed mode) or by ResultFly (OTP mode). ResultFly verifies the issuer against campaign configuration.
• Claims. Tokens must include iss (issuer), aud (ResultFly API audience), exp (expiry), and sub (subject/identity reference). Additional claims may describe identity type/provider as defined in the Identity documentation.
• Lifetime. Keep tokens short-lived (minutes) and refresh via the client identity flow. ResultFly enforces expiration based on exp.
• Responsibility. The client is responsible for protecting private keys/secrets used to sign JWTs and for ensuring that the subject truly represents the end user.

4. Authorization & Scopes

• Campaign-level access. API keys and user tokens are evaluated against campaign scopes. Calls referencing an unauthorized campaign are rejected.
• User-level isolation. JWT-based calls can only read or mutate State for the subject embedded in the token. Cross-user access is blocked.
• Forbidden operations. Attempts to modify system fields, undeclared variables, or resources outside the granted scope result in 403 Forbidden or 409 Conflict depending on operation. Administrative endpoints are accessible only with S2S keys.

Example: Authenticated API Requests

Server-to-Server request (API key)

curl -X POST https://api.resultfly.com/v1/external-events \
  -H "Authorization: Bearer rf_live_sk_8f3c1a_example_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "brand.pos",
    "external_event_id": "txn_987654321",
    "type": "purchase",
    "occurred_at": "2026-01-10T12:45:00Z",
    "identity": {
      "type": "loyalty_id",
      "value": "L-123456789"
    },
    "attributes": {
      "amount": 120.50,
      "currency": "USD",
      "store_id": "store_42"
    }
  }'

The API key travels in the Authorization header, identifying the integration rather than the end user. The request runs in a pure server-to-server context.

User-context request (JWT)

curl -X POST https://api.resultfly.com/v1/runtime/state:mutate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "cmp_abc123",
    "ops": [
      {
        "path": "state.user.loyalty_points",
        "op": "inc",
        "value": 10
      }
    ],
    "mutation_id": "mut_001"
  }'

The JWT represents the authenticated participant. ResultFly derives the user identity from the token and applies the mutation only to that user’s State.

Security Note: The tokens and keys shown above are examples only. Always store API keys and JWT signing secrets securely and never expose them in client-side code unless your integration model explicitly requires it.