External IDs for users

When a user is created in Stytch, they will be assigned a unique identifier that looks like a UUID. For your convenience, you may choose to additionally assign an "external ID" to a user which can then be used in any place where the Stytch user_id is expected.

When calling the Create User endpoint, you may pass in an optional external_id parameter. The external_id is a string consisting of alphanumeric, ., _, or - characters with a maximum length of 128 characters. External IDs must be unique across users in your project.

You may also set an external ID during a call to the Migrate Password endpoint, but only if the user does not yet exist and is created. If the user already exists, you must use the Update User endpoint to assign or reassign the external_id.

If a user has already been created, you may assign it an external_id later with the Update User endpoint. Similar to creation, pass in an external_id parameter and it will then be assigned to that user. Again, remember that external IDs must be unique within your project.

If you wish to change a user's external ID, you may use the same Update User endpoint listed above. After this point, you will no longer be able to refer to that user by its old external_id.

In any endpoint that expects a user_id, you may instead choose to pass in your custom-defined external_id. For clarity, all responses from Stytch will continue to use the Stytch-defined user_id, though external_id will exist as a subfield within the User object.