2025.04.04 | External IDs

We are excited to announce the launch of External IDs for Stytch! This new feature allows you to reference users, members, and organizations using an identifier that is meaningful to them.

What it is and why it is valuable:

External IDs enable you to pass in your own defined identifiers for users, members, and organizations, instead of relying solely on Stytch's assigned UUIDs. This offers benefits in situations like migrations, by simplifying the process for mapping existing IDs to Stytch's identifiers.

Furthermore, these external IDs can be used in search filters, addressing a common pain point when trying to locate users or members from a previous system within Stytch.

How to use External IDs today:

You can set External IDs in the following ways:

• Upon creation: External IDs can be included as a parameter in the CreateUser, CreateMember, and PasswordMigrate endpoints.

• Updating existing entities: You can set or update external IDs with an explicit call to UpdateUser or UpdateMember.

In the Stytch API:

• You can pass in an external ID wherever a user_id or member_id is expected (in path or body parameters).

• You can use an organization slug wherever an organization_id is expected.

• For the UserSearch and MemberSearch endpoints, external IDs can be used within the user_ids / member_ids search filter.

Here's an example of how you can use external_id in your Stytch API calls:

## Create a user with an external ID
curl -s -X POST https://api.stytch.com/v1/users \
        -H "Content-Type: application/json" \
        -u "$project:$secret" \
        -d '{
"email": "hello@stytch.example.com",
"external_id": "my-cool-user"
}' | jq .

## Get a user by external_id
curl -s -X GET https://api.stytch.com/v1/users/my-cool-user \
  -H "Content-Type: application/json" \
  -u "$project:$secret" | jq .

## Create a member with an external ID and use the org slug
curl -s -X POST https://api.stytch.com/v1/b2b/organizations/my-org-slug/members \
        -H "Content-Type: application/json" \
        -u "$project:$secret" \
        -d '{
"email_address": "hello@stytch.example.com", 
"external_id": "my-cool-member"
}' | jq .

## Get a member using the organization slug and member external ID
curl -s -X GET https://api.stytch.com/v1/b2b/organizations/my-org-slug/member \
        -H "Content-Type: application/json" \
        -u "$project:$secret" \
        --get \
        --data-urlencode 'member_id=my-cool-member' | jq .

You can find more detailed information on how to use External IDs in the updated Consumer and B2B documentation.

Where to find us

Stytch developer Slack

Join the discussion, ask questions, and suggest new features in our official Slack!

Get support

Check out the Stytch Forum or email us at support@stytch.com