feat(shared,js): add directory sync resource and organization contract

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});

.changeset/dir-sync-self-serve-wiring.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add self-serve Directory Sync (SCIM) setup. The `Organization` resource gains `getDirectorySync()` and `createDirectorySync()` for the directory bound to an enterprise connection, and the returned `DirectorySync` resource exposes `update()`, `rotateToken()`, `delete()`, and `getUsers()`; the SCIM bearer token is only returned by `createDirectorySync()` and `rotateToken()`. The `OrganizationProfile` Security page gains a Directory Sync section, and the internal `ConfigureDirectorySync` component walks through the setup. Both are only shown when the instance has self-serve Directory Sync enabled.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "552KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
+ { "path": "./dist/clerk.js", "maxSize": "553KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
  { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/src/core/resources/DirectorySync.ts

@@ -0,0 +1,177 @@
+import type {
+ ClerkPaginatedResponse,
+ DeletedObjectJSON,
+ DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncJSONSnapshot,
+ DirectorySyncProvider,
+ DirectorySyncResource,
+ DirectorySyncUserJSON,
+ DirectorySyncUserResource,
+ GetDirectorySyncUsersParams,
+ UpdateDirectorySyncParams,
+} from '@clerk/shared/types';
+
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './Base';
+import { DeletedObject } from './DeletedObject';
+
+export class DirectorySync extends BaseResource implements DirectorySyncResource {
+ id!: string;
+ name!: string;
+ organizationId!: string;
+ enterpriseConnectionId!: string;
+ endpointUrl!: string;
+ provider!: DirectorySyncProvider;
+ enabled!: boolean;
+ groupRoleMappingEnabled!: boolean;
+ attributeMapping: Record<string, string> = {};
+ apiKey: string | null = null;
+ createdAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null, organizationId: string) {
+ super();
+ this.organizationId = organizationId;
+ this.fromJSON(data);
+ }
+
+ private get directoryPath(): string {
+ return `/organizations/${this.organizationId}/enterprise_connections/${this.enterpriseConnectionId}/directory`;
+ }
+
+ update = async (params: UpdateDirectorySyncParams): Promise<DirectorySyncResource> => {
+ const body: Record<string, string | boolean> = {};
+ if (params.enabled !== undefined) {
+ body.enabled = params.enabled;
+ }
+ if (params.attributeMapping !== undefined) {
+ body.attribute_mapping = JSON.stringify(params.attributeMapping);
+ }
+
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: this.directoryPath,
+ method: 'PATCH',
+ body: body as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ rotateToken = async (): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `${this.directoryPath}/rotate_api_key`,
+ method: 'POST',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.organizationId);
+ };
+
+ delete = async (): Promise<DeletedObjectResource> => {
+ const json = (
+ await BaseResource._fetch<DeletedObjectJSON>({
+ path: this.directoryPath,
+ method: 'DELETE',
+ })
+ )?.response as unknown as DeletedObjectJSON;
+
+ return new DeletedObject(json);
+ };
+
+ getUsers = async (
+ params?: GetDirectorySyncUsersParams,
+ ): Promise<ClerkPaginatedResponse<DirectorySyncUserResource>> => {
+ const res = await BaseResource._fetch({
+ path: `${this.directoryPath}/users`,
+ method: 'GET',
+ search: convertPageToOffsetSearchParams(params),
+ });
+
+ const payload = res?.response as unknown as ClerkPaginatedResponse<DirectorySyncUserJSON> | undefined;
+
+ return {
+ total_count: payload?.total_count ?? 0,
+ data: (payload?.data ?? []).map(row => new DirectorySyncUser(row)),
+ };
+ };
+
+ protected fromJSON(data: DirectorySyncJSON | DirectorySyncJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.name = data.name;
+ this.enterpriseConnectionId = data.enterprise_connection_id;
+ this.endpointUrl = data.endpoint_url;
+ this.provider = data.provider;
+ this.enabled = data.enabled;
+ this.groupRoleMappingEnabled = data.group_role_mapping_enabled;
+ this.attributeMapping = data.attribute_mapping ?? {};
+ this.apiKey = data.api_key ?? null;
+ this.createdAt = unixEpochToDate(data.created_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): DirectorySyncJSONSnapshot {
+ return {
+ object: 'directory',
+ id: this.id,
+ name: this.name,
+ enterprise_connection_id: this.enterpriseConnectionId,
+ endpoint_url: this.endpointUrl,
+ provider: this.provider,
+ enabled: this.enabled,
+ group_role_mapping_enabled: this.groupRoleMappingEnabled,
+ attribute_mapping: this.attributeMapping,
+ // The bearer token is deliberately absent: snapshots may be persisted
+ // and the secret must never outlive the response it arrived on.
+ created_at: this.createdAt?.getTime() ?? 0,
+ updated_at: this.updatedAt?.getTime() ?? 0,
+ };
+ }
+}
+
+export class DirectorySyncUser extends BaseResource implements DirectorySyncUserResource {
+ id!: string;
+ userId!: string;
+ firstName: string | null = null;
+ lastName: string | null = null;
+ identifier: string | null = null;
+ imageUrl!: string;
+ hasImage!: boolean;
+ active!: boolean;
+ provisionedAt: Date | null = null;
+ updatedAt: Date | null = null;
+
+ constructor(data: DirectorySyncUserJSON | null) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: DirectorySyncUserJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.userId = data.user_id;
+ this.firstName = data.first_name;
+ this.lastName = data.last_name;
+ this.identifier = data.identifier;
+ this.imageUrl = data.image_url;
+ this.hasImage = data.has_image;
+ this.active = data.active;
+ this.provisionedAt = unixEpochToDate(data.provisioned_at);
+ this.updatedAt = unixEpochToDate(data.updated_at);
+
+ return this;
+ }
+}

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,11 +2,14 @@ import type {
  AddMemberParams,
  ClerkPaginatedResponse,
  ClerkResourceReloadParams,
+ CreateDirectorySyncParams,
  CreateOrganizationDomainParams,
  CreateOrganizationEnterpriseConnectionParams,
  CreateOrganizationParams,
  DeletedObjectJSON,
  DeletedObjectResource,
+ DirectorySyncJSON,
+ DirectorySyncResource,
  EnterpriseConnectionJSON,
  EnterpriseConnectionResource,
  EnterpriseConnectionTestRunInitJSON,
@@ -49,6 +52,7 @@ import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '..
 import {
  BaseResource,
  DeletedObject,
+ DirectorySync,
  EnterpriseConnection,
  EnterpriseConnectionTestRun,
  OrganizationInvitation,
@@ -274,6 +278,32 @@ export class Organization extends BaseResource implements OrganizationResource {
  };
  };
 
+ getDirectorySync = async (enterpriseConnectionId: string): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'GET',
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
+ createDirectorySync = async (
+ enterpriseConnectionId: string,
+ params?: CreateDirectorySyncParams,
+ ): Promise<DirectorySyncResource> => {
+ const json = (
+ await BaseResource._fetch<DirectorySyncJSON>({
+ path: `/organizations/${this.id}/enterprise_connections/${enterpriseConnectionId}/directory`,
+ method: 'POST',
+ body: { name: params?.name } as any,
+ })
+ )?.response as unknown as DirectorySyncJSON;
+
+ return new DirectorySync(json, this.id);
+ };
+
  getMembershipRequests = async (
  getRequestParam?: GetMembershipRequestParams,
  ): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>> => {

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -108,6 +108,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  enterpriseSSO: EnterpriseSSOSettings = {
  enabled: false,
  self_serve_sso: false,
+ self_serve_directory_sync: false,
  };
  passkeySettings: PasskeySettingsData = {
  allow_autofill: false,
@@ -225,7 +226,10 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
  this.attackProtection.enumeration_protection.enabled,
  },
  };
- this.enterpriseSSO = this.withDefault(data.enterprise_sso, this.enterpriseSSO);
+ this.enterpriseSSO = {
+ ...this.withDefault(data.enterprise_sso, this.enterpriseSSO),
+ self_serve_directory_sync: data.enterprise_sso?.self_serve_directory_sync ?? false,
+ };
  this.passkeySettings = this.withDefault(data.passkey_settings, this.passkeySettings);
  this.passwordSettings = data.password_settings
  ? {

packages/clerk-js/src/core/resources/__tests__/DirectorySync.test.ts

@@ -0,0 +1,123 @@
+import type { DirectorySyncJSON } from '@clerk/shared/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, DirectorySync } from '../internal';
+
+const ORG_ID = 'org_123';
+const DIRECTORY_PATH = `/organizations/${ORG_ID}/enterprise_connections/ec_123/directory`;
+
+const directoryJSON: DirectorySyncJSON = {
+ object: 'directory',
+ id: 'scimdir_1',
+ name: 'Acme Okta',
+ enterprise_connection_id: 'ec_123',
+ endpoint_url: 'https://api.example.com/scim/v2',
+ provider: 'okta',
+ enabled: false,
+ group_role_mapping_enabled: false,
+ attribute_mapping: { 'name.givenName': 'first_name' },
+ created_at: 1700000000000,
+ updated_at: 1700000000000,
+};
+
+function createDirectorySync(): DirectorySync {
+ return new DirectorySync(directoryJSON, ORG_ID);
+}
+
+describe('DirectorySync', () => {
+ it('scopes itself to the owning organization and connection', () => {
+ const directory = createDirectorySync();
+
+ expect(directory.organizationId).toBe(ORG_ID);
+ expect(directory.enterpriseConnectionId).toBe('ec_123');
+ expect(directory.apiKey).toBeNull();
+ expect(directory.__internal_toSnapshot()).not.toHaveProperty('api_key');
+ });
+
+ it('updates the directory, serializing the attribute mapping as JSON', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: { ...directoryJSON, enabled: true } }));
+
+ const result = await createDirectorySync().update({
+ enabled: true,
+ attributeMapping: { 'name.familyName': 'last_name', 'name.givenName': null },
+ });
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({
+ method: 'PATCH',
+ path: DIRECTORY_PATH,
+ body: {
+ enabled: true,
+ attribute_mapping: JSON.stringify({ 'name.familyName': 'last_name', 'name.givenName': null }),
+ },
+ });
+ expect(result.enabled).toBe(true);
+ expect(result.organizationId).toBe(ORG_ID);
+ });
+
+ it('rotates the bearer token', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { ...directoryJSON, api_key: 'ak_new' } }));
+
+ const result = await createDirectorySync().rotateToken();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'POST', path: `${DIRECTORY_PATH}/rotate_api_key` });
+ expect(result.apiKey).toBe('ak_new');
+ });
+
+ it('deletes the directory', async () => {
+ // @ts-ignore
+ BaseResource._fetch = vi
+ .fn()
+ .mockReturnValue(Promise.resolve({ response: { object: 'directory', id: 'scimdir_1', deleted: true } }));
+
+ const result = await createDirectorySync().delete();
+
+ // @ts-ignore
+ expect(BaseResource._fetch).toHaveBeenCalledWith({ method: 'DELETE', path: DIRECTORY_PATH });
+ expect(result.id).toBe('scimdir_1');
+ expect(result.deleted).toBe(true);
+ });
+
+ it('lists provisioned directory users with pagination', async () => {
+ const paginated = {
+ data: [
+ {
+ object: 'directory_user' as const,
+ id: 'scimdu_1',
+ user_id: 'user_1',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ identifier: 'ada@example.com',
+ image_url: '',
+ has_image: false,
+ active: true,
+ provisioned_at: 1700000000000,
+ updated_at: 1700000000000,
+ },
+ ],
+ total_count: 1,
+ };
+
+ // @ts-ignore
+ BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: paginated }));
+
+ const result = await createDirectorySync().getUsers({ initialPage: 2, pageSize: 10 });
+
+ // @ts-ignore
+ const call = BaseResource._fetch.mock.calls[0][0];
+ expect(call.method).toBe('GET');
+ expect(call.path).toBe(`${DIRECTORY_PATH}/users`);
+ expect(call.search.get('limit')).toBe('10');
+ expect(call.search.get('offset')).toBe('10');
+
+ expect(result.total_count).toBe(1);
+ expect(result.data[0].userId).toBe('user_1');
+ expect(result.data[0].identifier).toBe('ada@example.com');
+ expect(result.data[0].active).toBe(true);
+ });
+});