You should use the

external_id

field in Ory Kratos when you need to assign a unique, domain-specific identifier to each identity—such as a

customer_id

,

employee_id

, or similar. This is especially useful for: - Migrating from existing systems where you need to preserve user identifiers. - Supporting user-defined primary identifiers. - Querying and managing identities using a business-specific identifier rather than the internal UUID. - Using the

external_id

as the

sub

(subject) claim in JWTs, which can simplify integration with other systems and reduce mapping layers. The

external_id

must be unique across all identities. You cannot assign multiple

external_id

values to a single identity, nor can you have duplicate

external_id

values across different identities. If you attempt to import or create multiple identities with the same

external_id

, the operation will fail with a

409 Conflict

error. The

external_id

is a top-level attribute in API requests and is not part of the identity schema itself. There is no support for multiple

external_id

values per identity—each identity can have only one

external_id

at a time [External Identifiers](https://www.ory.sh/docs/kratos/manage-identities/external-id) [Migration guide](https://www.ory.sh/docs/kratos/manage-identities/external-id#migration-guide). In summary: - Use

external_id

for unique, external, domain-specific identifiers. - Each identity can have only one

external_id

, and it must be unique across all identities. - Multiple

external_id

values per identity are not supported.

@chilly-king-10285 how is external_id different from just adding 'customer_id'

The key difference is that

external_id

is a dedicated, top-level field managed by Ory Kratos itself, while adding a

customer_id

as a trait (e.g., in the identity schema under

traits.customer_id

) would make it just another user-editable attribute. Why use

external_id

instead of a trait like

customer_id

? - Uniqueness enforced by Kratos: The

external_id

must be unique across all identities. Kratos enforces this at the API/database level. If you use a trait like

customer_id

, you would need to enforce uniqueness yourself in your application logic. - Not user-editable: The

external_id

is not part of the identity schema and cannot be changed by the end user through self-service flows. Traits, including a

customer_id

trait, can be modified by the user or via the API. - API and JWT integration: Kratos provides dedicated API endpoints to query identities by

external_id

and allows you to use

external_id

as the

sub

claim in JWTs. This is not possible with a regular trait like

customer_id

 [External Identifiers](https://www.ory.sh/docs/kratos/manage-identities/external-id). - Migration and interoperability:

external_id

is designed for scenarios like system migrations, where you need to preserve or map external system identifiers directly and securely. Summary: Use

external_id

when you need a secure, unique, non-user-editable, and system-level identifier for an identity. Adding a

customer_id

as a trait does not provide these guarantees or integrations. [External Identifiers](https://www.ory.sh/docs/kratos/manage-identities/external-id)

@chilly-king-10285 what if I need multiple external_ids?

Ory Kratos does not support multiple

external_id

values per identity. The

external_id

is a dedicated, top-level field that must be unique across all identities, and each identity can have only one

external_id

at a time. If you attempt to assign more than one or use the same

external_id

for multiple identities, the operation will fail with a

409 Conflict

error [External Identifiers](https://www.ory.sh/docs/kratos/manage-identities/external-id). If your use case requires associating multiple external identifiers with a single identity, you would need to manage those additional identifiers yourself, for example by storing them in the identity's traits or metadata. However, these would not have the same uniqueness guarantees or API-level support as the official

external_id

field. In summary: - Only one

external_id

per identity is supported by Ory Kratos. - Multiple external IDs per identity are not natively supported.

@chilly-king-10285 How can I add a non-user-editable trait?

To add a non-user-editable attribute to an identity in Ory, you should use the metadata fields (

metadata_public

or

metadata_admin

), not traits. Traits are always user-editable via self-service flows or the Admin API, while metadata fields can only be set or updated via the Admin API and are not modifiable by the end user. - metadata_public: Visible to the user (e.g., via

/sessions/whoami

), but only modifiable by admins. - metadata_admin: Only visible and modifiable by admins. For example, to add a non-user-editable field:

json {   "identity": {     "traits": {       "email": "<mailto:user@example.com|user@example.com>"     },     "metadata_public": {       "customer_id": "123456"     },     "metadata_admin": {       "internal_notes": "VIP customer"     }   } }

You must use the Admin API to set or update these fields. They are not validated by the identity schema and cannot be changed by the user through self-service flows [Identity metadata & traits](https://www.ory.sh/docs/kratos/manage-identities/managing-users-identities-metadata). Summary: - Use

metadata_public

or

metadata_admin

for non-user-editable attributes. - Traits are always user-editable; metadata is not.