Role of externalId

[nomocas]

• Review the documentation: https://docs.clerk.dev/
• Go through package changelog files.

Hi All,

The context

We have a special case where all our users must be invited to use our app, and we don't want the invitee to go through clerk signup process. In fact, we only use clerk for sign-in through our custom components.

So, to allow them to sign in, we need to add our users in clerk DB only when they accept our invitation, programmatically through our backend (nodejs).

The question

What is the role of and how to use externalId?

We could add it through api:

createUser({
    externalId: '...',
    emailAddress:['[email protected]']
})

i.e.:

type CreateUserParams = {
  externalId?: string;
  emailAddress?: string[];
  phoneNumber?: string[];
  username?: string;
  password?: string;
  firstName?: string;
  lastName?: string;
  skipPasswordChecks?: boolean;
  skipPasswordRequirement?: boolean;
} & UserMetadataParams;

But we could not query with it:

• getUser(userId:string) returns a 404 as userId is not externalId
• and getUserList(params: UserListParams = {}) or getCount(params: UserListParams = {}) are using UserCountParams which does not contain it.

i.e.:

type UserCountParams = {
  emailAddress?: string[];
  phoneNumber?: string[];
  username?: string[];
  web3Wallet?: string[];
  query?: string;
  userId?: string[];
};

type UserListParams = UserCountParams & {
  limit?: number;
  offset?: number;
  orderBy?: 'created_at' | 'updated_at' | '+created_at' | '+updated_at' | '-created_at' | '-updated_at';
};

So how to use externalId?

If we add it in UserMetadataParams, same thing: how to query it through metadata as metadata are not allowed in UserCountParams

By the way: externalId is not shown in clerk dashboard (user section). I think it should be good to show it there.

Thanks for answering. ;)

[SokratisVidros]

@nomocas, externalID has been used only by few developers so far. However it's time to make it a first class user attribute.

The external ID is used to store the previous user id after migrating to Clerk. As you correctly pointed out we need to expose this field in Clerk Dashboard and make it searchable.

Meanwhile, we've already updated our JS frontend and backend SDKs to parse it correctly in #182. You should expect both fixes in Dashboard and Clerk Backend API by the end of this week.

Let me know if this helps your use case.

[SokratisVidros]

@nomocas FYI tomorrow morning (GMT+3) we will add search by external_id parameters in Clerk Backend API. Also external ID will be displayed in the user profile in Dashboard.

[nomocas]

Hi @SokratisVidros,

Perfect!

I'll give it a try tomorrow.

Thanks.

[SokratisVidros]

External ID is now available in Clerk JS. You can also search by it in Clerk Backend API.