User Identity

Many requests in MonetizationOS involve decisions for a specific user or session. To evaluate entitlements, surface behavior, metering, and plan assignment, MonetizationOS first resolves the request identity.

What is User Identity?

User identity is the canonical representation of who a request is for, including data about the user and their context. It powers access checks, surface decisions, workflow logic, usage tracking, and observability views.

When a request reaches MonetizationOS, it uses identity information provided with the request and any middleware workflows to resolve a single identity for that request. Workflows and APIs then operate on that normalized identity model.

Identity resolution affects:

• Which plans apply to a user or session
• How feature properties are evaluated
• Whether counters are incremented against a session or an authenticated user
• Which user record is shown in Observability and user journey tools

User data storage and segregation

User records are scoped by environment type, not by individual brands.

In practice:

• User data is shared across brands inside the same environment type
• User data is segregated between different environment types
• Any environment of the same type can read and update the same user identity records

This model allows multi-brand organizations to keep a unified user journey within an environment type, while preserving strict isolation between types such as Preview and Live.

Identity Types

For Surface Decisions, Access Checks, and Update Usage Counters, provide exactly one identity input per request, unless identity is being resolved in a middleware workflow:

• anonymousIdentifier
• userJwt
• userIdentifier

Anonymous identity (anonymousIdentifier)

Use anonymousIdentifier for unauthenticated traffic and pre-login sessions.

Common patterns:

• Generate a stable session identifier in your app or edge layer
• Persist it in a first-party cookie
• Reuse it across requests until the session lifecycle ends

This enables consistent metering, eligibility checks, and offer behavior before sign-in.

If you do not want or need to provide an identity up front, decision APIs support createAnonymousIdentifier. When enabled, MonetizationOS creates an anonymous identity if no other identity is resolved, returns it in the response, and lets you persist it for subsequent requests (for example, in a cookie). Using this option reduces round trips and lets MonetizationOS apply platform optimizations for anonymous identities.

JWT identity (userJwt)

Use userJwt for authenticated requests where identity is derived from a signed token.

Set it up as follows:

1. Configure an Authentication & Identity integration in MonetizationOS
2. Provide a valid JWT in the request
3. Ensure token claims map to your expected user identity and customer matching model

JWT identity is commonly used for client-side and edge-driven requests, especially when access decisions need claim-aware logic at runtime.

See Authentication & Identity for setup details.

Provided identity (userIdentifier)

Use userIdentifier when your backend already knows the canonical user ID and is making server-side calls.

Common scenarios:

• Your service already resolved authentication upstream
• You are calling APIs from trusted backend infrastructure

userIdentifier requires a secret key for decision APIs.

User types

Whichever identity input resolves a request, the result carries a canonical user type: anonymous or authenticated. This is the classification workflows and Observability use consistently, regardless of which mechanism produced it:

• anonymousIdentifier (including identities auto-created via createAnonymousIdentifier) resolves to an anonymous user
• userJwt and userIdentifier resolve to an authenticated user
• A middleware workflow that sets identity chooses which of the two applies

Workflows branch on this directly, for example to assign different plans to anonymous versus authenticated users in Dynamic Provisioning Workflows. Observability applies the same split when filtering and reporting on users.

Bot traffic is tracked separately from user type. Observability tags bot requests with source and bot-detection details rather than a third user type, so you can filter on human versus bot traffic independently of whether the underlying identity is anonymous or authenticated. See the Observability admin guide for how bot detections are surfaced.

Identity and API key type

Identity behavior depends on the key type used for the request:

• Public key (pk_*): Supports anonymousIdentifier and userJwt. Cannot use userIdentifier.
• Secret key (sk_*): Supports all identity types, including userIdentifier.

For server-side calls made with a secret key, you can also forward the original client user agent using x-mos-user-agent to preserve request context used by workflows and targeting logic.

For complete key behavior and auth details, see Webscale API overview.

Middleware workflows and identity

Middleware workflows run after the request identity is resolved, before MonetizationOS decision logic. They can identify users, enrich request context, and short-circuit requests before downstream workflows execute. When middleware sets identity, workflow identity reflects that origin with authType: "middleware".

This is useful for scenarios like deriving identity from custom headers, mapping device IDs to user IDs, classifying trusted bots before plan assignment, or adding shared context used by multiple downstream workflows.

See Middleware guide, MiddlewareWorkflowResult, and WorkflowIdentity.

Identity across workflows

After a request identity is resolved, workflows receive a normalized identity object.

This allows you to:

• Assign plans dynamically in Dynamic Provisioning Workflows
• Override feature behavior using identity-aware logic in Feature Workflows
• Personalize HTTP and component output in Surface Workflows and Component Workflows
• Trigger external orchestration with identity context in Action Workflows

For direct identity operations (linking, counters, and custom data), use identity utilities available in workflow runtimes.

Custom data on identities

Workflows can attach arbitrary custom data to a user or session identity, separate from plans, counters, and links. Use this to persist values a workflow computes or fetches, such as a segment, onboarding state, or a value sourced from an external system, and reuse it on later requests for the same identity.

The identity utilities support:

• writeCustomData: write or overwrite an item of custom data against an identity
• readCustomData: read a previously written item back
• deleteCustomData: remove an item

By default, custom data is scoped to the brand that wrote it. Pass the crossBrand option to share a value across every brand in the same environment type, consistent with how user records themselves are scoped.

Full read and write access to custom data is available in:

• Action Workflows
• Endpoint Workflows
• Surface Workflows and Component Workflows
• Middleware Workflows

Dynamic Provisioning Workflows receive a read-only view of identity utilities and can't write custom data. Feature Workflows don't receive identity utilities at all.

See WriteIdentityWorkflowUtils and ReadonlyIdentityWorkflowUtils for full method signatures.

Identity lifecycle and linking

A common production pattern is to begin with anonymous sessions and later link them to authenticated users after sign-in or conversion.

Identity linking helps you:

• Preserve user journey continuity from anonymous to authenticated states
• Carry forward usage and behavioral context
• Build a unified view in observability and analytics workflows

Use link relationships intentionally (for example, conversion flows) and define data-sharing behavior that matches your compliance and product requirements.

See Link Identities with an Endpoint for a worked example of linking an anonymous session to an authenticated user.

Identity in Observability

Every user identity accumulates a record of everything associated with it over time, viewable in Observability. See Users for what a user record includes and Data retention for how long that data is kept, and the Observability admin guide for how to inspect these records in the console.

Learn More

Getting Started guides

References

API references

Workflow references

Admin Guides

Recipes