Payloads

What is a payload?

A payload is a JSON object you define when creating a Forwarded Link. It can contain any valid JSON — strings, numbers, booleans, nested objects, arrays — as long as the total serialized size is under 8KB.

The payload is stored server-side and is not embedded in the token or in any client-facing URL. When the SDK resolves a session, the Forwarded API returns the full payload after validating the token and expiry. The payload is returned verbatim — Forwarded does not modify or interpret its fields.

You control the schema entirely. Your app reads the fields it expects and ignores the rest. This means different link versions can have different payload shapes, and your app can handle both gracefully.

Rules and limits

Maximum size: 8KB serialized JSON. If your use case requires more context, store the data in your own system and include a reference identifier (a UUID or database ID) in the payload. Your app fetches the full record from your backend using the identifier.

Do not include in payloads: passwords, payment card data, protected health information (PHI), raw cryptographic secrets, session tokens, long-lived access tokens, or any data you would not want transmitted in plaintext. Payloads are encrypted at rest but are returned in full to any client that presents a valid token.

Sessions are not a primary authentication mechanism. A resolved session proves that the bearer held a token issued for that specific link — it does not prove they are a specific user. Always verify user identity through your own authentication system before executing sensitive operations.

Schema versioning

Include a type or version field in every payload. This lets your app handle payloads from older link versions — a user who installed three weeks ago may be resolving a payload created before you updated the schema.

When you update a link's payload, only new sessions use the updated schema. Existing sessions (already CREATED or OPENED) retain their original payload. Version your payload-reading code accordingly, defaulting gracefully when a field is missing.

Templates

The Forwarded dashboard offers payload templates for common use cases: subscription offer, referral, invite, partner campaign, and QR campaign. Templates are suggested JSON starting points — they all use the same generic payload primitive underneath.

Using a template does not lock you into a schema. Edit the suggested fields, add custom ones, remove what you don't need, and publish. Templates are convenience defaults, not enforced contracts.