Skip to content
Dashboard
Theme
Theme

Profile and directory attributes

Discover standard fields, define bounded custom values, and map authenticated source attributes.

View Markdown

Use GET /v1/attribute_catalogue with an environment secret key to discover standard and predefined attributes and the environment’s custom definitions. See the management API and schemas.

Standard fields are idp_id, email, first_name, last_name and groups. Predefined values appear under attributes, including display_name, username, department_name, job_title, employee_number, manager_email, emails, phone_numbers and addresses. Read the catalogue for the complete list and declared types.

Core normalizes recognized SAML attribute names, OIDC claims and SCIM fields. Recognized SSO source names compare case-insensitively. Providers can omit values: a missing name or department remains missing. Predefined arrays are bounded to ten values; groups have separate handling.

Developers can save up to 50 environment-owned definitions through PUT /v1/attribute_catalogue. A key must match ^[a-z][a-z0-9_]{0,63}$ and must not collide with a standard or predefined key.

Type Wire value
string Nonempty UTF-8 string
string_array Array of nonempty UTF-8 strings; an empty array is permitted
boolean JSON true or false
integer Signed 64-bit JSON integer, from −9223372036854775808 to 9223372036854775807

Mappings belong independently to a connection or directory. They select an exact SAML attribute, OIDC claim or supported SCIM path. The target of a mapping is either a custom definition or a built-in profile attribute such as first_name, last_name, display_name or job_title (any catalogue string attribute). email and idp_id can never be targets, and neither can groups on a directory. Built-in mappings work on every plan; custom mappings need Business or Enterprise to save, and clearing them stays available after a downgrade. Management and authenticated portal APIs expose each owner’s attribute_map; a source path is data, never executable code. The only transforms are none, trim, lowercase, uppercase and first.

Conversion applies the transform, then the declared type, then bounds. SAML scalars need one value unless first selects one. SAML booleans accept exactly true, false, 1 or 0; integers use signed decimal without a plus sign, leading zeros or exponent. OIDC and SCIM use native JSON types without string coercion.

Each string or array item is at most 1 KiB of UTF-8 bytes; arrays have at most 100 items. One encoded attribute is at most 16 KiB and the complete custom_attributes object is at most 32 KiB. Invalid UTF-8, empty values after transformation, wrong types and unsupported values are omitted with a finite warning rather than failing the sign-in. Over the object budget, whole attributes are omitted in reverse key order; values are never truncated.

Mapped custom values appear under custom_attributes on profiles and directory users. A directory’s built-in mappings apply each time its users are read, in the API user view and the dsync.* event payloads, so a change shows at once without syncing the directory again. Removing a definition removes its mappings, except that a definition required by a portal profile cannot be removed. Custom attributes are application data and never become verified evidence for core sign-in policies.

The integer wire contract exceeds JavaScript’s exact number range. Use a parser that preserves signed 64-bit values before applying application logic; ordinary JSON.parse can lose precision. SDK support depends on the SDK version you use, so do not assume every SDK provides a lossless representation.

Attribute preview uses only the connection’s latest verified test sign-in. Its protected source is encrypted in Valkey, capped at 256 KiB and retained for at most 24 hours. A failed, expired or oversized latest test leaves no preview; core does not fall back to an older test or an ordinary sign-in.

Organization IT admins in the portal and members with environment:write can read the preview. Reads are audited without values and responses use no-store. Preview sources never contain raw XML, tokens or secrets and are not copied into logs, events, metrics, Workbench or debug bundles. Connection deletion, deactivation or an IdP change invalidates the source.

Use role rules and sign-in policies for their separate contracts. Your application still owns its permissions and must revoke sessions when a directory user is deprovisioned.