diff --git a/.changeset/document-sso-bypass-allowlist.md b/.changeset/document-sso-bypass-allowlist.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/document-sso-bypass-allowlist.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index 104be5a4a3b..74ea2fee966 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -72,6 +72,7 @@ const LINK_REPLACEMENTS = [ ['organization-membership-resource', '/docs/reference/types/organization-membership'], ['organization-suggestion-resource', '/docs/reference/types/organization-suggestion'], ['organization-resource', '/docs/reference/objects/organization'], + ['sso-bypass-allowlist-resource', '/docs/reference/types/sso-bypass-allowlist-resource'], ['organization-domain-resource', '/docs/reference/types/organization-domain-resource'], ['organization-invitation-resource', '/docs/reference/types/organization-invitation'], ['organization-membership-request-resource', '/docs/reference/types/organization-membership-request'], diff --git a/packages/shared/src/types/ssoBypassAllowlist.ts b/packages/shared/src/types/ssoBypassAllowlist.ts index 26e908a6bec..9caf5bbcb30 100644 --- a/packages/shared/src/types/ssoBypassAllowlist.ts +++ b/packages/shared/src/types/ssoBypassAllowlist.ts @@ -22,10 +22,12 @@ export interface SSOBypassAllowlistUserResource { } export type AddSSOBypassAllowlistUserParams = { + /** The ID of the Organization member to add. */ userId: string; }; export type AddSSOBypassAllowlistUsersParams = { + /** The IDs of the Organization members to add. */ userIds: string[]; }; @@ -40,33 +42,56 @@ export interface SSOBypassAllowlistBulkCreateJSON { } export interface SSOBypassAllowlistBulkCreateError { + /** The ID of the member who could not be added. */ userId: string; + /** The error code explaining why the member could not be added. */ code: string; } export interface SSOBypassAllowlistBulkCreateResult { + /** The allowlist entries created successfully. */ data: SSOBypassAllowlistUserResource[]; + /** The members who could not be added, each with a user ID and error code. */ errors: SSOBypassAllowlistBulkCreateError[]; } +/** + * The `SSOBypassAllowlistResource` object manages which Organization members can sign in with an email code instead of + * using their enterprise single sign-on (SSO) connection. Access it through `organization.ssoBypassAllowlist` on the + * [`Organization`](https://clerk.com/docs/reference/objects/organization#properties) object. + * + * Managing the allowlist requires the `org:sys_entconns_sso_bypass:manage` [System Permission](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#system-permissions). + * + * @interface + */ export interface SSOBypassAllowlistResource { /** - * Lists the members who may sign in with an email code when the organization's enterprise SSO is unavailable. - * Requires the `org:sys_entconns_sso_bypass:manage` permission. + * Lists the Organization members on the SSO bypass allowlist. + * + * @returns An array of `SSOBypassAllowlistUserResource` objects. */ getUsers: () => Promise; /** - * Adds a member to the allowlist. The member must hold a verified email address served by one of the - * organization's enterprise connections. + * Adds an Organization member to the allowlist. The member must have a verified email address on a domain served by + * one of the Organization's enterprise connections. + * + * @param params - An object with the `userId` of the Organization member to add. + * @returns The new `SSOBypassAllowlistUserResource` object. */ addUser: (params: AddSSOBypassAllowlistUserParams) => Promise; /** - * Adds several members to the allowlist, one request per 100 ids. Members who cannot be added are reported in - * `errors` with the same code `addUser` returns for them, and do not fail the batch. + * Adds Organization members to the allowlist in batches of 100. Members who cannot be added appear in `errors` with + * their `userId` and an error `code`; they do not prevent eligible members from being added to `data`. + * + * @param params - An object with the `userIds` of the Organization members to add. + * @returns An object with successfully added allowlist entries in `data` and rejected members in `errors`. */ addUsers: (params: AddSSOBypassAllowlistUsersParams) => Promise; /** - * Removes a member from the allowlist. + * Removes an Organization member from the allowlist. + * + * @param userId - The ID of the Organization member to remove. + * @returns A `DeletedObjectResource` object. */ removeUser: (userId: string) => Promise; }