User Attributes

User attributes are the profile fields you let your members keep on their own record. You define the list of attributes once for your organization — each with a name, a type, and a stable key — and then every member can have a value for each one.

Unlike raw member metadata, user attributes are controlled: only the attributes you have defined can be read or written through the Allegro APIs. This is the foundation for a member preference center, where a signed-in member can manage settings like newsletter opt-ins, content preferences, or a favorite topic.

How they work

You define attributes in Organization Settings → User Attributes.
Each attribute has a slug that maps to a single key on the member's profile. This is where the value is stored.
Each attribute has a type (text, number, boolean, color, or a fixed set of choices) that Allegro uses to validate and cast values.
Members set their own values through the Browser SDK, or your backend sets them through the REST API. See Setting values.
A member's current values are included in their signed session token (JWT) so your site can read them without an extra request.

Defining an attribute

Open Organization Settings → User Attributes and click New attribute. You provide:

Field	Required	Description
Attribute Name	Yes	The human-readable label, e.g. Wants Newsletter.
Slug	Yes	The key the value is stored under, e.g. `wants-newsletter`. Auto-filled from the name.
Description	No	An optional note describing what the attribute is for.
Category	No	Groups the attribute in the attribute list and on each member's Profile tab. Pick an existing category or type a new one. See Categories.
Type	Yes	How the value is validated and cast. See Attribute types.
Options	Enum	One choice per line. Shown and required only when the type is Select (enum).
Validation rules	No	Optional constraints each value must pass, each with an optional custom message. Available for Text and Number types only. See Validation rules.
Sync from external profiles	No	Ordered paths that fill this attribute automatically from a member's external profile data. See Syncing from external profiles.
Keep this field private	No	Hides the attribute from the Browser SDK and session API completely. See below.

The slug auto-fills as you type the name, but you can override it before saving.

Every attribute also has two visibility toggles.

Keep this field private hides the attribute from the browser entirely. When it's on, the Browser SDK and session API behave as if the attribute doesn't exist: it never appears in the member's session token, and reads and writes against its slug fail the same way an undefined slug does. A private attribute also can't be placed on a form. Admins, your backend using the token API, and webhooks are unaffected. Use this for values you record about a member but don't want exposed in their browser — an internal score or a churn risk flag, for example.

Allow field to be updated by the user controls writes only. When it's off, members can't change the value themselves through the Browser SDK or the session API — writes are rejected, though the member can still read the value. Admins and your backend, using the token API, can always update it regardless of this setting. Use this for attributes you want to drive from your own systems (like a membership tier) without a member being able to override them.

Private wins over the editable toggle: once an attribute is private, members can't read it either, so the editable toggle no longer applies and is disabled on the form.

The slug is permanent

The slug is the member profile key the value is stored under, so it cannot be changed after the attribute is created. On the edit form the slug field is locked. Pick it carefully — to rename the key you must delete the attribute and create a new one, which leaves the old values behind under the old slug.

Attribute types

Type	Stored value	Notes
Text	A string	Any free-form text.
Number	A number	Whole numbers or decimals.
Boolean	`true` / `false`	A simple on/off flag.
Select (enum)	One of a list	Must match one of the Options you defined, one per line.
Color	A hex color	A `#rrggbb` or `#rgb` value. Shorthand and uppercase are stored as lowercase six-digit hex, so `#ABC` is saved as `#aabbcc`.
File	An uploaded file	Admin only. Images (PNG, JPG, GIF, WebP) or the extensions you choose. See File attributes.

Allegro validates every incoming value against the attribute's type. A value that doesn't match — a non-number for a Number attribute, or a choice outside the list for a Select attribute — is rejected. Text and Number attributes can carry additional validation rules you configure; Boolean, Select, and Color attributes are constrained by their type alone.

File attributes

A File attribute holds one uploaded file per member, such as a headshot or a signed form. Only admins can set it: upload, replace, or remove the file from the member's Profile tab. Images show as a thumbnail; other files show as a download link.

When you define a File attribute, choose Allowed files:

Images accepts PNG, JPG, GIF, and WebP files. Allegro checks the file's contents, not just its name. Check Include SVG to also accept .svg files; scripts and external links are removed from every SVG on upload.
Specific extensions accepts the extensions you list, such as pdf, docx. Scripts, web pages, SVG, and executables are never allowed here; to accept SVG, choose Images and check Include SVG.

Files can be up to 10 MB.

Members can never upload or change a File attribute, so the Allow field to be updated by the user toggle, validation rules, and external profile sync don't apply, and a File attribute can't be placed on a form.

Keep this field private is on by default. While it's on, only admins can see the files: they never appear in the session token, the Browser SDK, or the REST API. Turn it off to make each member's file readable on your site. Its value is then the file's public URL, available through the session token, the Browser SDK, and the REST API. Choose when you create the attribute: this setting can't be changed afterward. File values are never sent on webhooks. Exports list the uploaded filename.

A File attribute can't be changed to another type, and an existing attribute can't be changed into a File attribute. Create a new attribute instead. Deleting a File attribute permanently removes every member's uploaded file for it.

Validation rules

Beyond the type check, you can add validation rules to a Text or Number attribute so every value has to meet your constraints — a maximum length, a numeric range, a required format, and so on. The rules apply everywhere a value is written: the Browser SDK, the session API, your backend through the REST API, and values synced from external profiles.

The Validation rules section appears on the attribute form only for Text and Number types. Click Add rule, pick a rule, and fill in its value. Each rule also has an optional Custom error message — the message a member sees when a value fails that rule. Leave it blank to use Allegro's built-in default.

Rule	Applies to	Value
Minimum length	Text	A whole number of characters.
Maximum length	Text	A whole number of characters.
Matches regex	Text	A regular expression, including its delimiters — e.g. `/^[a-z]+$/`.
Contains	Text	Text the value must include.
Does not contain	Text	Text the value must not include.
Is an email address	Text	No value — the value must be a valid email.
Minimum value	Number	The smallest allowed number.
Maximum value	Number	The largest allowed number.

You can add up to 20 rules per attribute, and each rule type can be used once.

Custom messages are your words to the member

The message you type on a rule is shown to the member — and returned to your site through the APIs — exactly as written, so keep it clear and specific (for example, "Enter a US ZIP code"). When you leave it blank, Allegro falls back to a generic default like "Must be no more than 40 characters."

Testing your rules

Configuring rules can be fiddly — a regex or a length bound is easy to get subtly wrong. The Test a value drawer lets you try a candidate value against the rules before you commit them. It appears on the attribute form for Text and Number attributes, on both the create and edit pages.

Open the drawer and type a value. Allegro checks it against the rules exactly as they stand in the form right now, including edits you haven't saved yet, and shows one row per check — the type check first, then each rule in order. Each row reports one of three outcomes:

Outcome	Meaning
Passed	The value satisfies the check.
Failed	The value violates the rule. The exact message a member would see is shown, including your custom message if you set one.
Not enforced	The rule can't run as configured — its value is missing, or its pattern is an invalid regex — so it accepts every value silently.

The verdict and messages are the real ones a member would receive, because the drawer runs the same server-side validation the APIs use rather than reimplementing it in the browser.

Watch for "not enforced" rules

A rule reported as not enforced is doing nothing — a value that looks like it passes it is really slipping through unchecked. This usually means a rule is missing its value or its regex is malformed. Fix the rule so it enforces what you intend before saving.

Editing an attribute

From the User Attributes list, click an attribute's name to edit its name, description, type, or options. The slug stays locked.

Changing the type of an attribute with existing values

Changing an attribute's type does not rewrite values members have already saved. Existing values are reinterpreted under the new type the next time they're read, which can produce unexpected results (for example, text that isn't a number becomes 0). Change the type of a live attribute with care.

Deleting an attribute

Deleting an attribute removes it from the list so it can no longer be read or written through the APIs or included in new tokens.

Member values are kept

Deleting an attribute definition does not erase the values members have already stored. The values remain on each member's profile under the slug. If you later re-create an attribute with the same slug, those existing values become visible again.

File attributes are the exception: deleting one permanently removes every member's uploaded file for it, and re-creating the slug starts empty.

Setting values

You don't set member values from the admin UI — they're set programmatically:

Members set their own values through the Allegro Browser SDK (allegro.member.setUserAttribute(...)). This is how a preference center on your site lets a signed-in member update their profile. See the User Attributes SDK guide.
Your backend sets values for any member through the REST API, under /v1/audience-members/{id}/user-attributes. Reading requires the audience-members:read scope; writing requires audience-members:write. See the REST API reference.
Admins upload File attribute values from the member's Profile tab. File values can't be set through the SDK or the REST API.

Writing to a slug that isn't a defined attribute is rejected — this is the control boundary that keeps arbitrary metadata out of the attribute APIs. Every write must also pass the attribute's type and any validation rules you configured; a value that fails is rejected with your custom error message.

Syncing from external profiles

Instead of setting an attribute's values yourself, you can have Allegro fill them automatically from a member's external profile data — the records Allegro syncs from your connected data providers. This is useful for surfacing a value that already lives in your CRM (a membership tier, a name, a preference) as a controlled user attribute your site and APIs can read.

Adding sync paths

On the attribute form, use the Sync from external profiles field to add one or more paths. Each path is the profile provider followed by the field's dot path into that provider's data — for example my_crm.name.full or my_crm.person.tier. As you type, the field suggests real paths drawn from your tenant's most recent external profiles.

Paths are checked in order, and the first one that resolves to a single value wins. Drag a path to reprioritize it, and use Add path to add more. This lets you list a primary source with fallbacks — if the first provider doesn't have the field for a given member, Allegro tries the next.

How the sync runs

Automatically, whenever a member's external profile is added, updated, or removed. When a profile that supplied a value is removed, Allegro falls back to the next matching path.
On save, when you add or change an attribute's paths, Allegro backfills every existing member who already has matching profile data.
On demand, using the Sync now link next to an attribute's Synced badge in the list. This re-runs the backfill across existing members — handy after editing paths. Sync now is rate limited to once per attribute per minute.

Synced values are written through the member's normal attribute value, so JWT claims, the APIs, and the SDK pick them up with no extra work.

Safety rules

Synced values still respect the attribute's type and any validation rules you configure. A value that fails validation (for example, a choice outside a Select attribute's options, or text longer than a Maximum length rule allows) is skipped rather than stored, non-scalar values are skipped, and an existing value is left untouched when no path resolves — so a sync never clears a value it can't replace.

Values in the session token

Each member's current attribute values are included in the signed session token (JWT) as a user_attributes claim, so your site can read a member's preferences directly from their token. Only attributes the member has a value for appear, private attributes never appear, and each value is cast to its declared type. See JWT Verification for the full token structure.

User Attributes SDK guide — Read and write a member's attributes from the browser.
JWT Verification — Read attribute values from the session token.
Members — Browse and manage your audience.

How they work​

Defining an attribute​

Attribute types​

Categories​

File attributes​

Validation rules​

Testing your rules​

Editing an attribute​

Deleting an attribute​

Setting values​

Syncing from external profiles​

Adding sync paths​

How the sync runs​

Values in the session token​

Related​