--- title: "Create a New Identity" method: POST path: "/v1/tenants/{tenant_id}/realms/{realm_id}/identities" tags: ["Identities"] --- # Create a New Identity `POST /v1/tenants/{tenant_id}/realms/{realm_id}/identities` ## Request - Base URL: `https://api-us.beyondidentity.com` - URL: `https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) To create an identity, send a POST request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/identities`. Values in the request body for read-only fields will be ignored. If the request conflicts with an existing resource, you will receive a 409 error. ## Path parameters - `tenant_id` string, required - `realm_id` string, required ## Request body - object: Request for CreateIdentity. - `identity` Identity, required: An identity is a unique identifier that may be used by an end-user to gain access governed by Beyond Identity. - `id` string: A unique identifier for the identity. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm. - `realm_id` string: A unique identifier for the identity's realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the identity's tenant. This is automatically set on creation. This field is immutable and read-only. - `display_name` string: A human-readable name for the identity. This name is used for display purposes. - `create_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the identity was created. This is automatically generated on creation. This field is read-only. - `update_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the identity was last updated. This is automatically updated when the identity is updated. This field is read-only. - `status` string: Indicator for the identity's administrative status. If 'active', the identity is able to generate passkeys and login. If 'suspended', the identity is unable to generate passkeys or login. - `traits` TraitsV0: Set of traits associated with an identity. - `type` string, required: The type of the traits schema. This value must be provided on all writes. - `username` string: A required, unique, case-insensitive username for an identity in the realm. - `primary_email_address` string: Email address serving as primary contact for identity. - `secondary_email_address` string: An additional email address for the user. - `external_id` string: An ID issued by the provisioning client. It is assumed that the value's uniqueness is controlled by the client setting the value. - `family_name` string: The family name or last name in most Western languages. - `given_name` string: The given name or first name in most Western languages. - `formatted_name` string: The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. "Ms. Barbara Jane Jensen, III"). - `middle_name` string: The middle name of the user, if applicable. - `honorific_prefix` string: Honorifics like "Mr.", "Mrs.", "Dr.", etc. - `honorific_suffix` string: Suffixes such as "Jr.", "Sr.", "III", etc. - `nick_name` string: A nickname the user goes by. - `title` string: The user's job title. - `primary_phone` string: The primary contact phone number for the user. - `secondary_phone` string: An additional phone number for the user. - `profile_url` string: A URL to the user's profile. - `photo` string: A URL to the user's photo. - `preferred_language` string: The user's preferred language. - `locale` string: The locale of the user, typically in the format of language-region. - `timezone` string: The timezone of the user. - `formatted_address` string: The full mailing address, formatted for display or use with a mailing label. This attribute MAY contain newlines. - `street_address` string: The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute MAY contain newlines. - `locality` string: The locality or city of the user. - `region` string: The region or state of the user. - `postal_code` string: The zip code or postal code of the user. - `country` string: The country of the user. - `user_type` string: Used to identify the relationship between the organization and the user. Typical values used might be 'Contractor', 'Employee', 'Intern', 'Temp', 'External', and 'Unknown', but any value may be used. - `employee_number` string: The employee number assigned to the user, typically based on order of hire or association with an organization. - `cost_center` string: The cost center associated with the user. - `organization` string: The organization the user belongs to. - `division` string: The division of the organization the user belongs to. - `department` string: The department of the organization the user belongs to. - `manager_id` string: The unique identifier for the user's manager. - `manager_name` string: The name of the user's manager. - `enrollment_status` 'ENROLLED' | 'PENDING' | 'INVITE_FAILED' | 'UNENROLLED': Indicator for the identity's enrollment status. If 'ENROLLED', the identity has 1 or more active passkeys. If 'PENDING', the identity has no active passkeys and 1 or more pending enrollments. If 'INVITE_FAILED', the identity has no active passkeys, no pending enrollments, and 1 or more failed enrollments. If 'UNENROLLED', the identity is not enrolled in the organization. May be undefined. This field is output-only. ## Response `200` The response will be a JSON object containing the standard attributes associated with an identity. - Identity: An identity is a unique identifier that may be used by an end-user to gain access governed by Beyond Identity. - `id` string: A unique identifier for the identity. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm. - `realm_id` string: A unique identifier for the identity's realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the identity's tenant. This is automatically set on creation. This field is immutable and read-only. - `display_name` string: A human-readable name for the identity. This name is used for display purposes. - `create_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the identity was created. This is automatically generated on creation. This field is read-only. - `update_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the identity was last updated. This is automatically updated when the identity is updated. This field is read-only. - `status` string: Indicator for the identity's administrative status. If 'active', the identity is able to generate passkeys and login. If 'suspended', the identity is unable to generate passkeys or login. - `traits` TraitsV0: Set of traits associated with an identity. - `type` string, required: The type of the traits schema. This value must be provided on all writes. - `username` string: A required, unique, case-insensitive username for an identity in the realm. - `primary_email_address` string: Email address serving as primary contact for identity. - `secondary_email_address` string: An additional email address for the user. - `external_id` string: An ID issued by the provisioning client. It is assumed that the value's uniqueness is controlled by the client setting the value. - `family_name` string: The family name or last name in most Western languages. - `given_name` string: The given name or first name in most Western languages. - `formatted_name` string: The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. "Ms. Barbara Jane Jensen, III"). - `middle_name` string: The middle name of the user, if applicable. - `honorific_prefix` string: Honorifics like "Mr.", "Mrs.", "Dr.", etc. - `honorific_suffix` string: Suffixes such as "Jr.", "Sr.", "III", etc. - `nick_name` string: A nickname the user goes by. - `title` string: The user's job title. - `primary_phone` string: The primary contact phone number for the user. - `secondary_phone` string: An additional phone number for the user. - `profile_url` string: A URL to the user's profile. - `photo` string: A URL to the user's photo. - `preferred_language` string: The user's preferred language. - `locale` string: The locale of the user, typically in the format of language-region. - `timezone` string: The timezone of the user. - `formatted_address` string: The full mailing address, formatted for display or use with a mailing label. This attribute MAY contain newlines. - `street_address` string: The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute MAY contain newlines. - `locality` string: The locality or city of the user. - `region` string: The region or state of the user. - `postal_code` string: The zip code or postal code of the user. - `country` string: The country of the user. - `user_type` string: Used to identify the relationship between the organization and the user. Typical values used might be 'Contractor', 'Employee', 'Intern', 'Temp', 'External', and 'Unknown', but any value may be used. - `employee_number` string: The employee number assigned to the user, typically based on order of hire or association with an organization. - `cost_center` string: The cost center associated with the user. - `organization` string: The organization the user belongs to. - `division` string: The division of the organization the user belongs to. - `department` string: The department of the organization the user belongs to. - `manager_id` string: The unique identifier for the user's manager. - `manager_name` string: The name of the user's manager. - `enrollment_status` 'ENROLLED' | 'PENDING' | 'INVITE_FAILED' | 'UNENROLLED': Indicator for the identity's enrollment status. If 'ENROLLED', the identity has 1 or more active passkeys. If 'PENDING', the identity has no active passkeys and 1 or more pending enrollments. If 'INVITE_FAILED', the identity has no active passkeys, no pending enrollments, and 1 or more failed enrollments. If 'UNENROLLED', the identity is not enrolled in the organization. May be undefined. This field is output-only. ## Other responses - `400`: Bad request. - `401`: Unauthorized. - `403`: Forbidden. - `404`: The resource was not found. - `409`: Conflict. - `500`: Server error. ## Changes - **2026-11-06** `42f3cac49392`: 1 info - added the optional property `enrollment_status` to the response with the `200` status [Operation history](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/changes/v1/tenants/:tenant_id/realms/:realm_id/identities/post.md) --- [API](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api.md) - [All operations](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/llms.txt) - [OpenAPI document](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/revisions/42f3cac49392?raw)