Custom attributes

Out of the box, every user has the standard fields: email, name, given_name, family_name, picture, locale. Custom attributes are everything else your tenant cares about.

Examples:

department: "engineering" — for routing or reporting.
employee_id: "E10342" — to cross-reference your HR system.
region: "eu-west" — for data-residency tagging.
beta_tester: true — to gate features in your app.
tier: "enterprise" — for SLA-aware feature flags.

Anything you'd reasonably want to filter, group, or read at runtime.

Define the schema

Settings → User schema → Custom attributes.

For each attribute:

Name — snake_case identifier. Used in JSON + on the access token.
Display name — what tenant admins see in the user detail UI.
Type — string / number / boolean / array<string>. JSON-friendly types only; no nested objects.
Required — whether a new user record must have this field set.
Default — value applied when a user is created without this attribute.
Description (optional) — bookkeeping note visible only to admins.

Save. The attribute is available immediately:

The user detail page's Profile tab shows a new section for custom attributes.
Bulk import accepts the field name.
The management API accepts it.
The user's access tokens carry the value as a custom claim (see "Surfacing to applications" below).

Edit on a user

User detail page → Profile tab → Custom attributes pane.

Each defined attribute appears as a field. Edit, save. Each save is one audit-log entry.

You can also set custom attributes on user create (in the form), via bulk import (per row), or programmatically (the management API).

Required vs optional

If you mark an attribute required, then:

Existing users without that attribute remain valid (no retroactive enforcement).
New users created without the attribute fail validation.
Bulk import rows without the attribute fail.
Editing a user to remove a required attribute fails.

A common pattern: define an attribute as required with a sensible default. New users get the default automatically; existing users keep their existing values.

Surfacing to applications

Custom attributes can be added to the access token your applications receive. Settings → User schema → Token claim mapping — for each attribute, choose:

Include in access token — adds a custom claim https://cymmetri.com/department (or your tenant's namespace) carrying the value.
Include in id token — same for the id token.
Userinfo only — accessible via /oauth2/userinfo but not embedded in tokens. Lighter tokens; one extra fetch on the application side.
Not surfaced — visible only to admins via the management API / admin console.

Default for new attributes: userinfo only. Tighter; the application explicitly asks for what it needs.

Naming conventions

The platform doesn't enforce a convention; some that work in practice:

snake_case identifiers for the attribute names (employee_id, cost_center).
One namespace prefix if you have many attributes from different sources (hr.department, crm.tier).
Boolean true/false rather than yes/no strings — your code's life is easier.
String enums rather than free-form when the values are constrained (tier: "free" | "pro" | "enterprise").

You can't change an attribute's type after it ships. Picking types deliberately on day one pays back.

Schema migration

If you need to rename an attribute or change its type, the right path is:

Add the new attribute alongside the old.
Backfill values via bulk import or a script.
Update your applications to read the new attribute.
Hide the old attribute (don't delete it yet) — set it to "not surfaced".
After a quarter of running on the new attribute with no issues, delete the old.

Deletion is permanent. Removing an attribute drops the values from every user record (the audit-log retention preserves the historical values, but the live record forgets them).

What custom attributes are NOT for

Passwords or secrets. Custom attributes are visible to admins + (via token claims) to your applications. They're metadata, not credentials.
Application-specific state that changes frequently. The user record is for identity attributes; per-application state belongs in your app's database, not on the user record.
PII you can't legally store on the IntelliAuth side. Health records, financial details — check the platform's data-handling commitments before putting them here.

Querying by custom attribute

The Users list view's search supports attr:<name>:<value> queries:

attr:department:engineering
attr:tier:enterprise

Combine with the standard filters. Useful for "find all enterprise users in the engineering department who haven't signed in in 90 days."

The management API supports the same query shape for programmatic filtering.