Identity & Authentication — Technical Overview

1. Identity Model Overview

ResultFly identifies users using a single stable external identity provided by the client. Different identity types (such as loyalty IDs, application tokens, or email-based identifiers) may be used depending on the integration mode, but only one identity is required to represent a user in the system.

Identities are the primary lookup keys. Every inbound call that touches campaign state resolves an IdentityRef first, and only then reads or mutates the user record. Because identities stem from client-controlled systems, they remain stable even when ResultFly pre-provisions users who have never opened the campaign UI.

2. IdentityRef Format

IdentityRef is the minimal contract ResultFly needs to recognize a person:

• type — describes the identity namespace (email, phone, loyalty_id, pos_token, etc.).
• provider — indicates who issues and governs the value (for example brand.crm, brand.app, resultfly). This prevents collisions when two sources use the same format.
• value — the stable string or hash the provider guarantees. ResultFly does not prescribe hashing algorithms; it only requires that the value stays consistent for the same person across requests.

Additional metadata (timestamps, source channel, verification flag) may accompany the ref, but the platform only depends on the three fields above to link identities to users.

3. Authentication Channels

ResultFly exposes two distinct authentication channels, each with its own authorization rules.

Server-to-Server (S2S)

• Uses API keys or service credentials issued per integration.
• Grants access to campaign-level operations, transaction ingestion, and administrative actions.
• Requests always contain explicit IdentityRef payloads because no end-user context exists.

User Context (In-App)

• Uses user tokens (JWT) minted by the client or ResultFly, depending on the identity mode.
• Applies rate and scope limits tied to the authenticated user so that in-app SDK calls only affect that user’s record.
• Requests carry implicit identity via the token; additional IdentityRef objects are optional unless the app is linking a new identifier.

4. User Resolution Flow

1. Resolve. ResultFly attempts to locate a user by the provided IdentityRef. If the identity already exists, the request continues with that user’s state.
2. Upsert. If no user is found, the caller may opt into upsert semantics: ResultFly creates a new user record, binds the identity, and returns the resulting user ID.
3. Pre-provision. Server-side systems can upsert identities long before a person visits the campaign interface. This allows brands to preload balances, loyalty tiers, or prize eligibility. When the participant later enters via mobile/web, the same identity instantly unlocks the pre-provisioned record.

If upsert is disabled and the identity is unknown, the API responds with 404 Not Found, signaling that the caller should either retry with a different identity or opt into creation.

5. Client-Managed Identity (JWT-Based)

• Issuer. The brand (or its identity provider) issues JWTs to the app or web client. ResultFly trusts the issuer configured for the campaign.
• Validation. ResultFly verifies signature, expiration, and audience, then extracts the identity claim.
• Minimum claims. Tokens must include: an identity value, identity type, provider identifier, and standard JWT fields (iss, exp, aud). No cryptographic algorithm is mandated beyond what the issuer and ResultFly agree on during onboarding.

This approach keeps PII on the client side. The JWT only carries the identity reference, so ResultFly can authenticate the user context without storing raw personal data.

6. ResultFly-Managed Identity (OTP)

When brands prefer ResultFly to identify users, the platform handles the entire verification loop:

1. The participant submits email or phone inside a ResultFly-hosted form or SDK widget.
2. ResultFly sends a one-time code (OTP) and validates the response.
3. After verification, ResultFly issues the user token and registers the verified identity as provider = resultfly.

This mode is commonly used for standalone activations, lead-generation, or situations where IT teams cannot provision their own token service. Server integrations can still attach additional identities later to align OTP-based users with CRM records.

7. Conflict Handling

ResultFly prevents duplicate identities within the same provider/type pair.

• If an upsert or identity-link call references an identity that already belongs to another user, the API returns 409 Conflict with the offending identity key.
• Automatic merges are deliberately out of scope now

8. Error Semantics

ResultFly uses standard HTTP status codes with consistent meaning across APIs:

• 401 Unauthorized. Authentication failed (invalid API key, expired JWT, bad signature). Retry only after fixing credentials.
• 403 Forbidden. Credentials are valid but lack permission for the requested campaign, scope, or action.
• 404 Not Found. The referenced campaign, node, or identity does not exist, or resolve was attempted without allowing upsert.
• 409 Conflict. A duplicate identity or incompatible state prevents the operation; caller action is required before retrying.

These semantics allow backend and app developers to treat Identity & Authentication as a predictable contract while leaving payload specifics to the API reference.