# Profile and directory attributes

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](/reference/api/management/) and [schemas](/reference/schemas/#attributecatalogue).

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.

## Define and map custom attributes

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.

## Bounds and omissions

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.

## Preview the latest test

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](/sso/role-rules/) and [sign-in policies](/sso/sign-in-policies/) for their separate contracts. Your application still owns its permissions and must revoke sessions when a directory user is deprovisioned.
