diff --git a/docs/references/astro/auth-store.mdx b/docs/references/astro/auth-store.mdx index d35f7d3b8e..dc2e1d19cb 100644 --- a/docs/references/astro/auth-store.mdx +++ b/docs/references/astro/auth-store.mdx @@ -11,35 +11,35 @@ The `$authStore` store provides a convenient way to access the current auth stat - `userId` - `string` - The current user's ID. + The ID of the current user. --- - `sessionId` - `string` - The current user's session ID. + The ID of the current session. --- - `orgId` - `string` - The current user's active organization ID. + The ID of the user's active organization. --- - `orgRole` - `string` - The current user's active organization role. + The current user's role in their active organization. --- - `orgSlug` - `string` - The current user's active organization slug. + The URL-friendly identifier of the user's active organization. ## How to use the `$authStore` store diff --git a/docs/references/backend/invitations/create-invitation.mdx b/docs/references/backend/invitations/create-invitation.mdx index 8145991681..32f8d30385 100644 --- a/docs/references/backend/invitations/create-invitation.mdx +++ b/docs/references/backend/invitations/create-invitation.mdx @@ -31,7 +31,7 @@ function createInvitation(params: CreateParams): Promise --- - `publicMetadata?` - - `{[string]: any}` + - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata. diff --git a/docs/references/backend/organization/create-organization-invitation.mdx b/docs/references/backend/organization/create-organization-invitation.mdx index dcf5ced83e..d3f3bfca4f 100644 --- a/docs/references/backend/organization/create-organization-invitation.mdx +++ b/docs/references/backend/organization/create-organization-invitation.mdx @@ -52,9 +52,9 @@ function createOrganizationInvitation( --- - `publicMetadata?` - - `{[string]: any}` + - [`OrganizationInvitationPublicMetadata`](/docs/references/javascript/types/metadata#organization-invitation-public-metadata) - Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API . + Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API. ## Example diff --git a/docs/references/backend/organization/create-organization-membership.mdx b/docs/references/backend/organization/create-organization-membership.mdx index f2fb9ed84c..5e8ee34b5f 100644 --- a/docs/references/backend/organization/create-organization-membership.mdx +++ b/docs/references/backend/organization/create-organization-membership.mdx @@ -19,14 +19,14 @@ function createOrganizationMembership( - `organizationId` - `string` - The organization ID of the organization a user is being added to. + The ID of the organization the user is being added to. --- - `userId` - `string` - The user ID of the user being added to the organization. + The ID of the user to be added to the organization. --- diff --git a/docs/references/backend/organization/create-organization.mdx b/docs/references/backend/organization/create-organization.mdx index 14b02dd2b4..f1fdb8fbc2 100644 --- a/docs/references/backend/organization/create-organization.mdx +++ b/docs/references/backend/organization/create-organization.mdx @@ -36,14 +36,14 @@ function createOrganization(params: CreateParams): Promise --- - `publicMetadata?` - - `{[string]: any}` + - [`OrganizationPublicMetadata`](/docs/references/javascript/types/metadata#organization-public-metadata) - Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API . + Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API. --- - `privateMetadata?` - - `{[string]: any}` + - [`OrganizationPrivateMetadata`](/docs/references/javascript/types/metadata#organization-private-metadata) Metadata that is only visible to your [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. diff --git a/docs/references/backend/organization/delete-organization-membership.mdx b/docs/references/backend/organization/delete-organization-membership.mdx index 56d9fe5729..7c581b7cca 100644 --- a/docs/references/backend/organization/delete-organization-membership.mdx +++ b/docs/references/backend/organization/delete-organization-membership.mdx @@ -26,7 +26,7 @@ function getOrganizationList( - `userId` - `string` - The user ID to remove from the organization. + The ID of the user to be removed from the organization. ## Example diff --git a/docs/references/backend/organization/update-organization-membership-metadata.mdx b/docs/references/backend/organization/update-organization-membership-metadata.mdx index d46f78f7af..d35f615ff8 100644 --- a/docs/references/backend/organization/update-organization-membership-metadata.mdx +++ b/docs/references/backend/organization/update-organization-membership-metadata.mdx @@ -31,14 +31,14 @@ function updateOrganizationMembershipMetadata( --- - `publicMetadata?` - - `{[string]: any}` + - [`OrganizationMembershipPublicMetadata`](/docs/references/javascript/types/metadata#organization-membership-public-metadata) - Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API . + Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API. --- - `privateMetadata?` - - `{[string]: any}` + - [`OrganizationMembershipPrivateMetadata`](/docs/references/javascript/types/metadata#organization-membership-private-metadata) Metadata that is only visible to your [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. diff --git a/docs/references/backend/organization/update-organization-membership.mdx b/docs/references/backend/organization/update-organization-membership.mdx index 977f311eb7..8c4cfebf07 100644 --- a/docs/references/backend/organization/update-organization-membership.mdx +++ b/docs/references/backend/organization/update-organization-membership.mdx @@ -19,14 +19,14 @@ function updateOrganizationMembership( - `organizationId` - `string` - The organization ID of the organization a user belongs to. + The ID of the organization this membership belongs to. --- - `userId` - `string` - The ID of the user. + The ID of the user that this membership belongs to. --- diff --git a/docs/references/backend/organization/update-organization-metadata.mdx b/docs/references/backend/organization/update-organization-metadata.mdx index 880a7c8dde..db0d49dde8 100644 --- a/docs/references/backend/organization/update-organization-metadata.mdx +++ b/docs/references/backend/organization/update-organization-metadata.mdx @@ -25,14 +25,14 @@ function updateOrganizationMetadata( --- - `publicMetadata?` - - `{[string]: any}` + - [`OrganizationPublicMetadata`](/docs/references/javascript/types/metadata#organization-public-metadata) Metadata that can be read from both the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API . --- - `privateMetadata?` - - `{[string]: any}` + - [`OrganizationPrivateMetadata`](/docs/references/javascript/types/metadata#organization-private-metadata) Metadata that is only visible to your [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. diff --git a/docs/references/backend/organization/update-organization.mdx b/docs/references/backend/organization/update-organization.mdx index de931931e2..4e326a8409 100644 --- a/docs/references/backend/organization/update-organization.mdx +++ b/docs/references/backend/organization/update-organization.mdx @@ -34,16 +34,16 @@ function updateOrganization(params: UpdateOrganizationParams): Promise diff --git a/docs/references/backend/types/backend-invitation.mdx b/docs/references/backend/types/backend-invitation.mdx index c44ab693ac..bba320eebd 100644 --- a/docs/references/backend/types/backend-invitation.mdx +++ b/docs/references/backend/types/backend-invitation.mdx @@ -11,7 +11,7 @@ The Backend `Invitation` object represents an invitation to join your applicatio - `id` - `string` - A unique identifier for the `Invitation`. + The unique identifier for the `Invitation`. --- @@ -25,21 +25,21 @@ The Backend `Invitation` object represents an invitation to join your applicatio - `publicMetadata` - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) - Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API . + Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata. --- - `createdAt` - `number` - Date when the `Invitation` was first created. + The date when the `Invitation` was first created. --- - `updatedAt` - `number` - Date of the last time the `Invitation` was updated. + The date when the `Invitation` was last updated. --- diff --git a/docs/references/backend/types/backend-organization-invitation.mdx b/docs/references/backend/types/backend-organization-invitation.mdx index 56923f64fc..39b8aeee0e 100644 --- a/docs/references/backend/types/backend-organization-invitation.mdx +++ b/docs/references/backend/types/backend-organization-invitation.mdx @@ -11,7 +11,7 @@ The Backend `OrganizationInvitation` object is similar to the [`OrganizationInvi - `id` - `string` - A unique identifier for the invitation. + The unique identifier for the `OrganizationInvitation`. --- @@ -39,14 +39,14 @@ The Backend `OrganizationInvitation` object is similar to the [`OrganizationInvi - `createdAt` - `number` - Date when the invitation was first created. + The date when the invitation was first created. --- - `updatedAt` - `number` - Date of the last time the invitation was updated. + The date when the invitation was last updated. --- @@ -58,14 +58,14 @@ The Backend `OrganizationInvitation` object is similar to the [`OrganizationInvi --- - `publicMetadata` - - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) + - [`OrganizationInvitationPublicMetadata`](/docs/references/javascript/types/metadata#organization-invitation-public-metadata) Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. --- - `privateMetadata` - - [`UserPrivateMetadata`](/docs/references/javascript/types/metadata#user-private-metadata) + - [`OrganizationInvitationPrivateMetadata`](/docs/references/javascript/types/metadata#organization-invitation-private-metadata) Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. diff --git a/docs/references/backend/types/backend-organization-membership.mdx b/docs/references/backend/types/backend-organization-membership.mdx index f9432af273..d18d84bbd2 100644 --- a/docs/references/backend/types/backend-organization-membership.mdx +++ b/docs/references/backend/types/backend-organization-membership.mdx @@ -11,7 +11,7 @@ The Backend `OrganizationMembership` object is similar to the [`OrganizationMemb - `id` - `string` - A unique identifier for the membership. + The unique identifier for the membership. --- @@ -23,14 +23,14 @@ The Backend `OrganizationMembership` object is similar to the [`OrganizationMemb --- - `publicMetadata` - - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) + - [`OrganizationMembershipPublicMetadata`](/docs/references/javascript/types/metadata#organization-membership-public-metadata) Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. --- - `privateMetadata` - - [`UserPrivateMetadata`](/docs/references/javascript/types/metadata#user-private-metadata) + - [`OrganizationMembershipPrivateMetadata`](/docs/references/javascript/types/metadata#organization-membership-private-metadata) Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. @@ -39,14 +39,14 @@ The Backend `OrganizationMembership` object is similar to the [`OrganizationMemb - `createdAt` - `number` - Date when the membership was first created. + The date when the membership was first created. --- - `updatedAt` - `number` - Date of the last time the membership was updated. + The date when the membership was last updated. --- @@ -69,7 +69,7 @@ The Backend `OrganizationMembership` object is similar to the [`OrganizationMemb - `identifier` - `string` - The identifier of the user. + The [identifier](/docs/authentication/configuration/sign-up-sign-in-options#identifier) of the user. --- diff --git a/docs/references/backend/types/backend-organization.mdx b/docs/references/backend/types/backend-organization.mdx index 888b7957c9..1cbb6b6e94 100644 --- a/docs/references/backend/types/backend-organization.mdx +++ b/docs/references/backend/types/backend-organization.mdx @@ -11,7 +11,7 @@ The Backend `Organization` object is similar to the [`Organization`](/docs/refer - `id` - `string` - A unique identifier for the organization. + The unique identifier for the organization. --- @@ -25,7 +25,7 @@ The Backend `Organization` object is similar to the [`Organization`](/docs/refer - `slug` - `string` - The organization slug. If supplied, it must be unique for the instance. + The URL-friendly identifier of the user's active organization. If supplied, it must be unique for the instance. --- @@ -39,14 +39,14 @@ The Backend `Organization` object is similar to the [`Organization`](/docs/refer - `createdAt` - `number` - Date when the organization was first created. + The date when the organization was first created. --- - `updatedAt` - `number` - Date of the last time the organization was updated. + The date when the organization was last updated. --- @@ -65,14 +65,14 @@ The Backend `Organization` object is similar to the [`Organization`](/docs/refer --- - `publicMetadata` - - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) + - [`OrganizationPublicMetadata`](/docs/references/javascript/types/metadata#organization-public-metadata) Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. --- - `privateMetadata` - - [`UserPrivateMetadata`](/docs/references/javascript/types/metadata#user-private-metadata) + - [`OrganizationPrivateMetadata`](/docs/references/javascript/types/metadata#organization-private-metadata) Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. diff --git a/docs/references/backend/types/backend-redirect-url.mdx b/docs/references/backend/types/backend-redirect-url.mdx index bbf111e356..bf2fda71ba 100644 --- a/docs/references/backend/types/backend-redirect-url.mdx +++ b/docs/references/backend/types/backend-redirect-url.mdx @@ -13,7 +13,7 @@ The Backend `RedirectUrl` object represents a redirect URL in your application. - `id` - `string` - A unique identifier for the redirect URL. + The unique identifier for the redirect URL. --- @@ -27,12 +27,12 @@ The Backend `RedirectUrl` object represents a redirect URL in your application. - `createdAt` - `number` - Date when the redirect URL was first created. + The date when the redirect URL was first created. --- - `updatedAt` - `number` - Date of the last time the redirect URL was updated. + The date when the redirect URL was last updated. diff --git a/docs/references/backend/types/backend-session.mdx b/docs/references/backend/types/backend-session.mdx index 2e9124eb48..b353539a0d 100644 --- a/docs/references/backend/types/backend-session.mdx +++ b/docs/references/backend/types/backend-session.mdx @@ -11,7 +11,7 @@ The Backend `Session` object is similar to the [`Session`](/docs/references/java - `id` - `string` - A unique identifier for the `Session`. + The unique identifier for the `Session`. --- @@ -60,12 +60,12 @@ The Backend `Session` object is similar to the [`Session`](/docs/references/java - `createdAt` - `number` - Date when the `Session` was first created. + The date when the `Session` was first created. --- - `updatedAt` - `number` - Date of the last time the `Session` was updated. + The date when the `Session` was last updated. diff --git a/docs/references/backend/types/backend-user.mdx b/docs/references/backend/types/backend-user.mdx index 70fb019b9e..5f65f9b76f 100644 --- a/docs/references/backend/types/backend-user.mdx +++ b/docs/references/backend/types/backend-user.mdx @@ -11,7 +11,7 @@ The Backend `User` object is similar to the `User` object as it holds informatio - `id` - `string` - A unique identifier for the user. + The unique identifier for the user. --- @@ -53,14 +53,14 @@ The Backend `User` object is similar to the `User` object as it holds informatio - `createdAt` - `number` - Date when the user was first created. + The date when the user was first created. --- - `updatedAt` - `number` - Date of the last time the user was updated. + The date when the user was last updated. --- @@ -81,35 +81,35 @@ The Backend `User` object is similar to the `User` object as it holds informatio - `primaryEmailAddressId` - `string` - The unique identifier for the `EmailAddress` that the user has set as primary. + The ID for the `EmailAddress` that the user has set as primary. --- - `primaryPhoneNumberId` - `string` - The unique identifier for the `PhoneNumber` that the user has set as primary. + The ID for the `PhoneNumber` that the user has set as primary. --- - `primaryWeb3WalletId` - `string` - The unique identifier for the [`Web3Wallet`][web3-ref] that the user signed up with. + The ID for the [`Web3Wallet`][web3-ref] that the user signed up with. --- - `lastSignInAt` - `number` - Date when the user last signed in. May be empty if the user has never signed in. + The date when the user last signed in. May be empty if the user has never signed in. --- - `externalId` - `string` - The unique identifier for the user in the external system. + The ID of the user as used in your external systems. Must be unique across your instance. --- @@ -151,7 +151,7 @@ The Backend `User` object is similar to the `User` object as it holds informatio - `unsafeMetadata` - [`UserUnsafeMetadata`](/docs/references/javascript/types/metadata#user-unsafe-metadata) - Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the `User` object.
There is also an `unsafeMetadata` attribute in the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object. The value of that field will be automatically copied to the user's unsafe metadata once the sign up is complete. + Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. --- diff --git a/docs/references/backend/types/saml-connection.mdx b/docs/references/backend/types/saml-connection.mdx index 08f8ba4f13..8cea088b7b 100644 --- a/docs/references/backend/types/saml-connection.mdx +++ b/docs/references/backend/types/saml-connection.mdx @@ -11,7 +11,7 @@ The Backend `SamlConnection` object holds information about a SAML connection fo - `id` - `string` - A unique identifier for the connection. + The unique identifier for the connection. --- @@ -53,7 +53,7 @@ The Backend `SamlConnection` object holds information about a SAML connection fo - `createdAt` - `number` - Date when the connection was first created. + The date when the connection was first created. --- @@ -137,7 +137,7 @@ The Backend `SamlConnection` object holds information about a SAML connection fo - `updatedAt` - `number` - Date of the last time the SAML connection was updated. + The date when the SAML connection was last updated. --- diff --git a/docs/references/backend/user/create-user.mdx b/docs/references/backend/user/create-user.mdx index d912e6615b..2c12262335 100644 --- a/docs/references/backend/user/create-user.mdx +++ b/docs/references/backend/user/create-user.mdx @@ -23,7 +23,7 @@ function createUser(params: CreateUserParams): Promise - `externalId?` - `string` - The ID of the user you use in your external systems. Must be unique across your instance. + The ID of the user as used in your external systems. Must be unique across your instance. --- @@ -181,23 +181,23 @@ function createUser(params: CreateUserParams): Promise --- - `publicMetadata?` - - `Record` + - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) - Metadata saved on the user, that is visible to both your Frontend and Backend APIs. + Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. --- - `privateMetadata?` - - `Record` + - [`UserPrivateMetadata`](/docs/references/javascript/types/metadata#user-private-metadata) - Metadata saved on the user that is only visible to your Backend API. + Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. --- - `unsafeMetadata?` - - `Record` + - [`UserUnsafeMetadata`](/docs/references/javascript/types/metadata#user-unsafe-metadata) - Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. **Note:** Since this data can be modified from the frontend, it is not guaranteed to be safe. + Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. --- diff --git a/docs/references/backend/user/get-count.mdx b/docs/references/backend/user/get-count.mdx index b4b16232e7..34339ab543 100644 --- a/docs/references/backend/user/get-count.mdx +++ b/docs/references/backend/user/get-count.mdx @@ -19,49 +19,49 @@ The total count of users can be filtered down by adding one or more of these par - `emailAddress?` - `string[]` - The email addresses to filter by. + Counts users with emails that match the given query, via case-insensitive partial match. For example, `hello` will match a user with the email `hello@example.com`. --- - `phoneNumber?` - `string[]` - The phone numbers to filter by. + Counts users with phone numbers that match the given query, via case-insensitive partial match. For example, `555` will match a user with the phone number `+1555xxxxxxx`. --- - `externalId?` - `string[]` - The external ID's to filter by. + Counts users with the specified external IDs. --- - `username?` - `string[]` - The usernames to filter by. + Counts users with the specified usernames. --- - `web3wallet?` - `string[]` - The Web3 wallet address to filter by. + Counts users with the specified Web3 wallet addresses. --- - `userId?` - `string` - The user ID's to filter by. + Counts users with the user IDs specified. --- - `query?` - `string` - Counts users that match the given query. For possible matches, we check the email addresses, phone numbers, usernames, Web3 wallet addresses, user IDs, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. + Counts users that match the given query. For possible matches, Clerk checks the email addresses, phone numbers, usernames, Web3 wallet addresses, user IDs, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. ## Examples @@ -79,9 +79,7 @@ console.log(response) ### Filter by query -To do a broader match through a list of fields, you can use the query parameter which partially matches the fields: `userId`, `emailAddress`, `phoneNumber`, `username`, `web3Wallet`, and `externalId`. - -This example retrieves the total number of users matching the query `test`. +The following example retrieves the total number of users matching the query `test`. ```tsx const response = await clerkClient.users.getCount({ query: 'test' }) diff --git a/docs/references/backend/user/get-user-oauth-access-token.mdx b/docs/references/backend/user/get-user-oauth-access-token.mdx index e75f7979a1..f10d5a69f0 100644 --- a/docs/references/backend/user/get-user-oauth-access-token.mdx +++ b/docs/references/backend/user/get-user-oauth-access-token.mdx @@ -20,7 +20,7 @@ function getUserOauthAccessToken( - `userId` - `string` - The ID of the user to retrieve. + The ID of the user to retrieve the OAuth access token for. --- diff --git a/docs/references/backend/user/update-user-metadata.mdx b/docs/references/backend/user/update-user-metadata.mdx index 7101085538..add9f190e2 100644 --- a/docs/references/backend/user/update-user-metadata.mdx +++ b/docs/references/backend/user/update-user-metadata.mdx @@ -19,21 +19,21 @@ function updateUserMetadata(userId: string, params: UpdateUserMetadataParams): P - `userId` - `string` - The ID of the organization to update. + The ID of the user to update. --- - `publicMetadata?` - - `Record` + - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) - Metadata saved on the organization, that is visible to both your Frontend and Backend APIs. + Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. --- - `privateMetadata?` - - `Record` + - [`UserPrivateMetadata`](/docs/references/javascript/types/metadata#user-private-metadata) - Metadata saved on the organization that is only visible to your Backend API. + Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. ## Example diff --git a/docs/references/backend/user/update-user.mdx b/docs/references/backend/user/update-user.mdx index 4675846a50..6289f57a46 100644 --- a/docs/references/backend/user/update-user.mdx +++ b/docs/references/backend/user/update-user.mdx @@ -77,10 +77,6 @@ function updateUser(userId: string, params: UpdateUserParams): Promise --- - - be used when providing a `password`. - - --- - - `profileImageID?` - `string` @@ -126,7 +122,7 @@ function updateUser(userId: string, params: UpdateUserParams): Promise - `signOutOfOtherSessions?` - `boolean` - Set to `true` to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a `password`. + Set to `true` to sign out the user from all their active sessions once their password is updated. Can only be used when providing the `password` parameter. --- @@ -145,23 +141,23 @@ function updateUser(userId: string, params: UpdateUserParams): Promise --- - `publicMetadata?` - - `Record` + - [`UserPublicMetadata`](/docs/references/javascript/types/metadata#user-public-metadata) - Metadata saved on the user, that is visible to both your Frontend and Backend APIs. + Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. Updating this property will override the existing metadata. To merge metadata, use [`updateUserMetadata()`](/docs/references/backend/user/update-user-metadata). --- - `privateMetadata?` - - `Record` + - [`UserPrivateMetadata`](/docs/references/javascript/types/metadata#user-private-metadata) - Metadata saved on the user that is only visible to your Backend API. + Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. Updating this property will override the existing metadata. To merge metadata, use [`updateUserMetadata()`](/docs/references/backend/user/update-user-metadata). --- - `unsafeMetadata?` - - `Record` + - [`UserUnsafeMetadata`](/docs/references/javascript/types/metadata#user-unsafe-metadata) - Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. **Note:** Since this data can be modified from the frontend, it is not guaranteed to be safe. + Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. --- @@ -203,7 +199,21 @@ function updateUser(userId: string, params: UpdateUserParams): Promise - `createdAt?` - `Date` - A custom date/time denoting when the user signed up to the application, specified in RFC3339 format

For example: `2012-10-20T07:15:20.902Z`. + A custom date/time denoting when the user signed up to the application, specified in RFC3339 format. For example: `2012-10-20T07:15:20.902Z`. + + --- + + - `skipLegalChecks?` + - `boolean` + + When set to `true` all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. + + --- + + - `legalAcceptedAt?` + - `Date` + + A custom date/time denoting when the user accepted legal requirements, specified in RFC3339 format. For example: `2012-10-20T07:15:20.902Z`. ## Example diff --git a/docs/references/javascript/client.mdx b/docs/references/javascript/client.mdx index d6bd7d3646..0e0e30d0f1 100644 --- a/docs/references/javascript/client.mdx +++ b/docs/references/javascript/client.mdx @@ -41,7 +41,7 @@ The `Client` object also holds information about any sign in or sign up attempts - `lastActiveSessionId` - `string` - Unique identifier of the last active [`Session`](/docs/references/javascript/session) on this client. + The ID of the last active [`Session`](/docs/references/javascript/session) on this client. --- diff --git a/docs/references/javascript/email-address.mdx b/docs/references/javascript/email-address.mdx index 4170f3439a..4e28707ad1 100644 --- a/docs/references/javascript/email-address.mdx +++ b/docs/references/javascript/email-address.mdx @@ -16,7 +16,7 @@ Email addresses must be **verified** to ensure that they can be assigned to thei - `id` - `string` - A unique identifier for this email address. + The unique identifier for this email address. --- diff --git a/docs/references/javascript/external-account.mdx b/docs/references/javascript/external-account.mdx index 098f0b92e8..794ad55744 100644 --- a/docs/references/javascript/external-account.mdx +++ b/docs/references/javascript/external-account.mdx @@ -13,7 +13,7 @@ External account must be verified, so that you can make sure they can be assigne - `id` - `string` - A unique identifier for this external account. + The unique identifier for this external account. --- @@ -81,9 +81,9 @@ External account must be verified, so that you can make sure they can be assigne --- - `publicMetadata` - - `Record \| null = {}` + - `Record` - Metadata provided about the user from the provider. + Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. --- diff --git a/docs/references/javascript/organization-domain.mdx b/docs/references/javascript/organization-domain.mdx index f6702183bd..aef0633d63 100644 --- a/docs/references/javascript/organization-domain.mdx +++ b/docs/references/javascript/organization-domain.mdx @@ -11,7 +11,7 @@ The `OrganizationDomain` object is the model around an organization domain. - `id` - `string` - A unique identifier for this organization domain. + The unique identifier for this organization domain. --- @@ -67,14 +67,14 @@ The `OrganizationDomain` object is the model around an organization domain. - `createdAt` - `Date` - The date and time the organization domain was created. + The date when the organization domain was created. --- - `updatedAt` - `Date` - The date and time the organization domain was updated. + The date when the organization domain was last updated. ### `OrganizationDomainVerification` diff --git a/docs/references/javascript/organization-invitation.mdx b/docs/references/javascript/organization-invitation.mdx index 75f381d778..9fe22c0ade 100644 --- a/docs/references/javascript/organization-invitation.mdx +++ b/docs/references/javascript/organization-invitation.mdx @@ -11,7 +11,7 @@ The `OrganizationInvitation` object is the model around an organization invitati - `id` - `string` - A unique identifier for this organization invitation. + The unique identifier for this organization invitation. --- @@ -32,7 +32,7 @@ The `OrganizationInvitation` object is the model around an organization invitati - `publicMetadata` - [`OrganizationInvitationPublicMetadata`](/docs/references/javascript/types/metadata#organization-invitation-public-metadata) - The public metadata of the organization invitation. + Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. --- @@ -53,14 +53,14 @@ The `OrganizationInvitation` object is the model around an organization invitati - `createdAt` - `Date` - Date of the time the invitation was created. + The date when the invitation was created. --- - `updatedAt` - `Date` - Date of the last time the invitation was updated. + The date when the invitation was last updated. ### `OrganizationCustomRoleKey` diff --git a/docs/references/javascript/organization-membership-request.mdx b/docs/references/javascript/organization-membership-request.mdx index ec6fcf9d13..b5b4c7799d 100644 --- a/docs/references/javascript/organization-membership-request.mdx +++ b/docs/references/javascript/organization-membership-request.mdx @@ -11,7 +11,7 @@ The `OrganizationMembershipRequest` object is the model that describes the reque - `id` - `string` - A unique identifier for this membership request. + The unique identifier for this membership request. --- @@ -39,14 +39,14 @@ The `OrganizationMembershipRequest` object is the model that describes the reque - `createdAt` - `Date` - The date and time the membership request was created. + The date when the membership request was created. --- - `updatedAt` - `Date` - The date and time the membership request was updated. + The date when the membership request was last updated. ## Methods diff --git a/docs/references/javascript/organization-membership.mdx b/docs/references/javascript/organization-membership.mdx index abbb61d65d..7d5ad75e26 100644 --- a/docs/references/javascript/organization-membership.mdx +++ b/docs/references/javascript/organization-membership.mdx @@ -11,7 +11,7 @@ The `OrganizationMembership` object is the model around an organization membersh - `id` - `string` - A unique identifier for this organization membership. + The unique identifier for this organization membership. --- @@ -46,14 +46,14 @@ The `OrganizationMembership` object is the model around an organization membersh - `createdAt` - `Date` - Date of the time the membership was created. + The date when the membership was created. --- - `updatedAt` - `Date` - Date of the last time the membership was updated. + The date when the membership was last updated. ## Methods diff --git a/docs/references/javascript/organization/members.mdx b/docs/references/javascript/organization/members.mdx index b5aaf8ef96..d8381880de 100644 --- a/docs/references/javascript/organization/members.mdx +++ b/docs/references/javascript/organization/members.mdx @@ -69,7 +69,7 @@ function addMember(params: AddMemberParams): Promise - `userId` - `string` - The ID of the user that will be added as a member to the organization. + The ID of the user to be added as a member to the organization. --- @@ -99,7 +99,7 @@ function updateMember(params: UpdateMembershipParams): Promise - `userId` - `string` - The user identifier. + The ID of the user to remove from the organization. ### Returns diff --git a/docs/references/javascript/organization/organization.mdx b/docs/references/javascript/organization/organization.mdx index 0f6247cc8c..24b8b112aa 100644 --- a/docs/references/javascript/organization/organization.mdx +++ b/docs/references/javascript/organization/organization.mdx @@ -79,14 +79,14 @@ The following examples assume: - `createdAt` - `Date` - Date of the time the organization was created. + The date when the organization was created. --- - `updatedAt` - `Date` - Date of the last time the organization was updated. + The date when the organization was last updated. --- @@ -385,16 +385,16 @@ An _experimental_ interface that includes information about a user's role. --- - `createdAt` - - `string` + - `Date` - The date and time the role was created. + The date when the role was created. --- - `updatedAt` - - `string` + - `Date` - The date and time the role was last updated. + The date when the role was last updated. #### `PermissionResource` @@ -431,16 +431,16 @@ An _experimental_ interface that includes information about a user's permission. --- - `createdAt` - - `string` + - `Date` - The date and time the role was created. + The date when the role was created. --- - `updatedAt` - - `string` + - `Date` - The date and time the role was last updated. + The date when the permission was last updated. #### Example diff --git a/docs/references/javascript/phone-number.mdx b/docs/references/javascript/phone-number.mdx index 5182b9993b..520eca4b27 100644 --- a/docs/references/javascript/phone-number.mdx +++ b/docs/references/javascript/phone-number.mdx @@ -18,7 +18,7 @@ Finally, phone numbers can be used as part of [multi-factor authentication](/doc - `id` - `string` - A unique identifier for this phone number. + The unique identifier for this phone number. --- diff --git a/docs/references/javascript/session-with-activities.mdx b/docs/references/javascript/session-with-activities.mdx index 281f475e6f..3d5cbb718c 100644 --- a/docs/references/javascript/session-with-activities.mdx +++ b/docs/references/javascript/session-with-activities.mdx @@ -15,7 +15,7 @@ While the `SessionWithActivities` object wraps the most important information ar - `id` - `string` - A unique identifier for the session. + The unique identifier for the session. --- @@ -73,7 +73,7 @@ function revoke(): Promise - `id` - `string` - A unique identifier for the session activity record. + The unique identifier for the session activity record. --- diff --git a/docs/references/javascript/session.mdx b/docs/references/javascript/session.mdx index 51b016f679..87a0196a95 100644 --- a/docs/references/javascript/session.mdx +++ b/docs/references/javascript/session.mdx @@ -22,7 +22,7 @@ All sessions that are **expired**, **removed**, **replaced**, **ended** or **aba - `id` - `string` - A unique identifier for the session. + The unique identifier for the session. --- @@ -78,7 +78,7 @@ All sessions that are **expired**, **removed**, **replaced**, **ended** or **aba - `createdAt` - `Date` - The time the session was created. + The date when the session was created. --- diff --git a/docs/references/javascript/sign-in/first-factor.mdx b/docs/references/javascript/sign-in/first-factor.mdx index 2191b569ca..13eabee842 100644 --- a/docs/references/javascript/sign-in/first-factor.mdx +++ b/docs/references/javascript/sign-in/first-factor.mdx @@ -36,21 +36,21 @@ function prepareFirstFactor(params: PrepareFirstFactorParams): Promise - `emailAddressId?` - `string` - Unique identifier for the user's email address that will receive an email message with the one-time authentication code. This parameter will work only when the `email_code` strategy is specified. + The ID for the user's email address that will receive an email message with the one-time authentication code. This parameter will work only when the `email_code` strategy is specified. --- - `phoneNumberId?` - `string` - Unique identifier for the user's phone number that will receive an SMS message with the one-time authentication code. This parameter will work only when the `phone_code` strategy is specified. + The ID for the user's phone number that will receive an SMS message with the one-time authentication code. This parameter will work only when the `phone_code` strategy is specified. --- - `web3WalletId?` - `string` - Unique identifier for the user's Web3 wallet address. This parameter will work only when the `strategy` is set to `web3_metamask_signature`, `web3_coinbase_wallet_signature`, or `web3_okx_wallet_signature`. + The ID for the user's Web3 wallet address. This parameter will work only when the `strategy` is set to `web3_metamask_signature`, `web3_coinbase_wallet_signature`, or `web3_okx_wallet_signature`. --- diff --git a/docs/references/javascript/types/metadata.mdx b/docs/references/javascript/types/metadata.mdx index 707c482f8e..789b721de6 100644 --- a/docs/references/javascript/types/metadata.mdx +++ b/docs/references/javascript/types/metadata.mdx @@ -18,6 +18,16 @@ interface OrganizationPublicMetadata { } ``` +## `OrganizationPrivateMetadata` + +A type that represents the private metadata for an organization. + +```ts +interface OrganizationPrivateMetadata { + [k: string]: unknown +} +``` + ## `OrganizationInvitationPublicMetadata` A type that represents the public metadata for an organization invitation. @@ -28,6 +38,16 @@ interface OrganizationInvitationPublicMetadata { } ``` +## `OrganizationInvitationPrivateMetadata` + +A type that represents the private metadata for an organization invitation. + +```ts +interface OrganizationInvitationPrivateMetadata { + [k: string]: unknown +} +``` + ## `OrganizationMembershipPublicMetadata` A type that represents the public metadata for an organization membership. @@ -38,6 +58,16 @@ interface OrganizationMembershipPublicMetadata { } ``` +## `OrganizationMembershipPrivateMetadata` + +A type that represents the private metadata for an organization membership. + +```ts +interface OrganizationMembershipPrivateMetadata { + [k: string]: unknown +} +``` + ## `SignUpUnsafeMetadata` A type that represents the unsafe metadata for a sign-up. @@ -48,6 +78,16 @@ interface SignUpUnsafeMetadata { } ``` +## `UserOrganizationInvitationPublicMetadata` + +A type that represents the public metadata for a user organization invitation. + +```ts +interface UserOrganizationInvitationPublicMetadata { + [k: string]: unknown +} +``` + ## `UserPublicMetadata` A type that represents the public metadata for a user. diff --git a/docs/references/javascript/types/passkey-resource.mdx b/docs/references/javascript/types/passkey-resource.mdx index 4fe9c56b45..8092140303 100644 --- a/docs/references/javascript/types/passkey-resource.mdx +++ b/docs/references/javascript/types/passkey-resource.mdx @@ -7,14 +7,47 @@ An interface that describes a passkey associated with a user response. ## Properties -| Properties | Type | Description | -| - | - | - | -| `id` | `string` | The passkey's unique ID generated by Clerk. | -| `verification` | [`Verification`](/docs/references/javascript/types/verification#verification) | Verification details for the passkey. | -| `name` | `string` | The passkey's name. | -| `createdAt` | `string` | The date and time when the passkey was created. | -| `updatedAt` | `string` | The date and time when the passkey was updated. | -| `lastUsedAt` | `string` | The date and time when the passkey was last used. | + + - `id` + - `string` + + The unique identifier of the passkey. + + --- + + - `name` + - `string` + + The passkey's name. + + --- + + - `verification` + - [`Verification`](/docs/references/javascript/types/verification#verification) + + The verification details for the passkey. + + --- + + - `createdAt` + - `Date` + + The date when the passkey was created. + + --- + + - `updatedAt` + - `Date` + + The date when the passkey was last updated. + + --- + + - `lastUsedAt` + - `Date | null` + + The date when the passkey was last used. + ## Methods diff --git a/docs/references/javascript/types/user-organization-invitation.mdx b/docs/references/javascript/types/user-organization-invitation.mdx index 6f3a9a8f86..5f9403835b 100644 --- a/docs/references/javascript/types/user-organization-invitation.mdx +++ b/docs/references/javascript/types/user-organization-invitation.mdx @@ -11,7 +11,7 @@ The `OrganizationInvitation` object is the model around an organization invitati - `id` - `string` - A unique identifier for this organization invitation. + The unique identifier for this organization invitation. --- @@ -36,7 +36,7 @@ The `OrganizationInvitation` object is the model around an organization invitati --- - `publicMetadata` - - [`OrganizationInvitationPublicMetadata`](/docs/references/javascript/types/metadata#organization-invitation-public-metadata) + - [`UserOrganizationInvitationPublicMetadata`](/docs/references/javascript/types/metadata#user-organization-invitation-public-metadata) The public metadata of the organization invitation. @@ -59,14 +59,14 @@ The `OrganizationInvitation` object is the model around an organization invitati - `createdAt` - `Date` - Date of the time the invitation was created. + The date when the invitation was created. --- - `updatedAt` - `Date` - Date of the last time the invitation was updated. + The date when the invitation was last updated. ### `OrganizationCustomRoleKey` diff --git a/docs/references/javascript/user/totp.mdx b/docs/references/javascript/user/totp.mdx index 14b5890bd6..15346bae17 100644 --- a/docs/references/javascript/user/totp.mdx +++ b/docs/references/javascript/user/totp.mdx @@ -65,7 +65,7 @@ function createBackupCode(): Promise - `id` - `string` - A unique identifier for this TOTP secret + The unique identifier for this TOTP secret. --- @@ -100,14 +100,14 @@ function createBackupCode(): Promise - `createdAt` - `Date` - Creation date of the TOTP secret + The date when the TOTP secret was created. --- - `updatedAt` - `Date` - Update timestamp of the TOTP secret + The date when the TOTP secret was last updated. ## `BackupCodeResource` @@ -116,28 +116,28 @@ function createBackupCode(): Promise - `id` - `string` - A unique identifier for this TOTP secret + The unique identifier for this TOTP secret. --- - `codes` - `string[]` - The generated set of backup codes + The generated set of backup codes. --- - `createdAt` - `Date` - Creation date of the TOTP secret + The date when the backup codes were created. --- - `updatedAt` - `Date` - Update timestamp of the TOTP secret + The date when the backup codes were last updated. ## TOTP example diff --git a/docs/references/javascript/user/user.mdx b/docs/references/javascript/user/user.mdx index 69b3927afa..f687aee1e7 100644 --- a/docs/references/javascript/user/user.mdx +++ b/docs/references/javascript/user/user.mdx @@ -17,7 +17,7 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to - `id` - `string` - A unique identifier for the user. + The unique identifier for the user. --- @@ -80,7 +80,7 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to - `primaryEmailAddressId` - `string | null` - The unique identifier for the `EmailAddress` that the user has set as primary. + The ID for the `EmailAddress` that the user has set as primary. --- @@ -108,7 +108,7 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to - `primaryPhoneNumberId` - `string | null` - The unique identifier for the `PhoneNumber` that the user has set as primary. + The ID for the `PhoneNumber` that the user has set as primary. --- @@ -129,7 +129,7 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to - `primaryWeb3WalletId` - `string | null` - The unique identifier for the [`Web3Wallet`][web3-ref] that the user signed up with. + The ID for the [`Web3Wallet`][web3-ref] that the user signed up with. --- @@ -241,14 +241,14 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to - `privateMetadata` - [`UserPrivateMetadata`](/docs/references/javascript/types/metadata#user-private-metadata) - Metadata that can be read and set only from the Backend API. + Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. --- - `unsafeMetadata` - [`UserUnsafeMetadata`](/docs/references/javascript/types/metadata#user-unsafe-metadata) - Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the `User` object.
There is also an `unsafeMetadata` attribute in the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object. The value of that field will be automatically copied to the user's unsafe metadata once the sign up is complete. + Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend.
There is also an `unsafeMetadata` attribute in the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object. The value of that field will be automatically copied to the user's unsafe metadata once the sign up is complete. --- @@ -260,23 +260,23 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to --- - `lastSignInAt` - - `Date` + - `Date | null` - Date when the user last signed in. May be empty if the user has never signed in. + The date when the user last signed in. `null` if the user has never signed in. --- - `createdAt` - `Date` - Date when the user was first created. + The date when the user was first created. --- - `updatedAt` - `Date` - Date of the last time the user was updated. + The date when the user was last updated. ## Methods @@ -320,21 +320,21 @@ All props below are optional. - `primaryEmailAddressId` - `string` - The unique identifier for the [`EmailAddress`][email-ref] that the user has set as primary. + The ID for the [`EmailAddress`][email-ref] that the user has set as primary. --- - `primaryPhoneNumberId` - `string` - The unique identifier for the [`PhoneNumber`][phone-ref] that the user has set as primary. + The ID for the [`PhoneNumber`][phone-ref] that the user has set as primary. --- - `primaryWeb3WalletId` - `string` - The unique identifier for the [`Web3Wallet`][web3-ref] that the user signed up with. + The ID for the [`Web3Wallet`][web3-ref] that the user signed up with. --- diff --git a/docs/references/javascript/web3-wallet/web3-wallet.mdx b/docs/references/javascript/web3-wallet/web3-wallet.mdx index 42591c0f61..edc2b952b3 100644 --- a/docs/references/javascript/web3-wallet/web3-wallet.mdx +++ b/docs/references/javascript/web3-wallet/web3-wallet.mdx @@ -17,7 +17,7 @@ The second and final step involves an attempt to complete the verification by ca - `id` - `string` - A unique identifier for this Web3 wallet. + The unique identifier for the Web3 wallet. --- diff --git a/docs/references/nextjs/auth-object.mdx b/docs/references/nextjs/auth-object.mdx index 7ccbab87e2..16f3011c3e 100644 --- a/docs/references/nextjs/auth-object.mdx +++ b/docs/references/nextjs/auth-object.mdx @@ -11,35 +11,35 @@ The `Auth` object contains important information like the current user's session - `sessionId` - `string` - The current user's session ID. + The ID of the current session. --- - `userId` - `string` - The current user's unique identifier. + The ID of the current user. --- - `orgId` - `string | undefined` - The current user's active organization ID. + The ID of the user's active organization. --- - `orgRole` - [OrganizationCustomRoleKey](#organization-custom-role-key) | undefined - The current user's active organization role. + The current user's role in their active organization. --- - `orgSlug` - - `string |undefined` + - `string | undefined` - The current user's active organization slug. + The URL-friendly identifier of the user's active organization. --- @@ -60,7 +60,7 @@ The `Auth` object contains important information like the current user's session - `actor` - `ActClaim | undefined` - Holds identifier for the user that is impersonating the current user. + Holds identifier for the user that is impersonating the current user. Read more about [impersonation](/docs/users/user-impersonation). --- diff --git a/docs/references/react-router/get-auth.mdx b/docs/references/react-router/get-auth.mdx index 9715c265c6..3707ba4fcd 100644 --- a/docs/references/react-router/get-auth.mdx +++ b/docs/references/react-router/get-auth.mdx @@ -1,9 +1,9 @@ --- title: '`getAuth()`' -description: The getAuth() helper retrieves authentication state from the request object. +description: Access and manage the current user's authentication state in your React application with Clerk's getAuth() helper. --- -The `getAuth()` helper retrieves authentication state from the request object. +The `getAuth()` helper retrieves the current user's authentication state from the request object. ## Parameters diff --git a/docs/references/react/use-auth.mdx b/docs/references/react/use-auth.mdx index c0e02b5ed7..755e0fb304 100644 --- a/docs/references/react/use-auth.mdx +++ b/docs/references/react/use-auth.mdx @@ -1,111 +1,118 @@ --- title: '`useAuth()`' -description: Clerk's useAuth() hook is a convenient way to access the current auth state. +description: Access and manage authentication state in your React application with Clerk's useAuth() hook. --- -The `useAuth()` hook provides information about the current auth state, as well as helper methods to manage the current active session. +The `useAuth()` hook provides access to the current user's authentication state and methods to manage the active session. -## `useAuth()` returns +## Returns - - `isSignedIn` + - `isLoaded` - `boolean` - A boolean that returns true if the user is signed in. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- - - `isLoaded` + - `isSignedIn` - `boolean` - A boolean that until Clerk loads and initializes, will be set to `false`. Once Clerk loads, `isLoaded` will be set to `true`. + A boolean that indicates whether a user is currently signed in. --- - `userId` - `string` - The current user's ID. + The ID of the current user. --- - `sessionId` - `string` - The current user's session ID. + The ID for the current session. --- - `orgId` - `string` - The current user's active organization ID. + The ID of the user's active organization. --- - `orgRole` - `string` - The current user's active organization role. + The current user's role in their active organization. --- - `orgSlug` - `string` - The current user's organization slug. + The URL-friendly identifier of the user's active organization. --- - `signOut()` - `(options?: SignOutOptions) => Promise` - A function that signs the user out. See the [reference documentation](/docs/references/javascript/clerk/clerk#sign-out) for more information. - - --- + A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](/docs/references/javascript/clerk/clerk#sign-out). - `getToken()` - `(options?: GetTokenOptions) => Promise` - A function that returns a promise that resolves to the current user's session token. Can also be used to retrieve a custom JWT template. See the [reference documentation](/docs/references/javascript/session#get-token) for more information. + A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the [reference doc](/docs/references/javascript/session#get-token). --- - `has()` - `(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean` - A function that returns a boolean based on the permission or role provided as parameter. Can be used for authorization. See the [reference documentation](/docs/references/nextjs/auth-object#has){{ target: '_blank' }} for more information. + A function that checks if the user has specific permissions or roles. See the [reference doc](/docs/references/nextjs/auth-object#has). ## How to use the `useAuth()` hook > [!NOTE] -> For Next.js apps, it's recommended to use the [`auth()`](/docs/references/nextjs/auth) helper instead of the `useAuth()` hook. Since `auth()` is used in server components, you'll need to pass the auth data to Client Components as needed. If you prefer to use the `useAuth()` hook, pass the `dynamic` prop to the `` component, but note that this switches the app to dynamic rendering. Learn more [here](/docs/references/nextjs/rendering-modes). +> For Next.js applications, it's recommended to use the [`auth()`](/docs/references/nextjs/auth) helper instead of `useAuth()`. Since `auth()` must be used in Server Components, you'll need to pass auth data to Client Components as needed. If you prefer `useAuth()`, you must pass the `dynamic` prop to ``, but be aware this switches the app to dynamic rendering. Learn more [here](/docs/references/nextjs/rendering-modes). -The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also demonstrates a basic example of how you could use the `getToken()` method to retrieve a session token for fetching data from an external resource. +The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource. -```tsx {{ filename: 'external-data-page.tsx' }} +```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }} import { useAuth } from '@clerk/clerk-react' export default function ExternalDataPage() { const { getToken, isLoaded, isSignedIn } = useAuth() + const fetchExternalData = async () => { + const token = await getToken() + + // Fetch data from an external API + const response = await fetch('https://api.example.com/data', { + headers: { + Authorization: `Bearer ${token}`, + }, + }) + + return response.json() + } + if (!isLoaded) { - // Handle loading state however you like return
Loading...
} if (!isSignedIn) { - // Handle signed out state however you like return
Sign in to view this page
} - const fetchDataFromExternalResource = async () => { - const token = await getToken() - // Add logic to fetch your data - return data - } - - return
...
+ return ( +
+ +
+ ) } ``` diff --git a/docs/references/react/use-clerk.mdx b/docs/references/react/use-clerk.mdx index a0d87ff1c1..d8c3fd21f1 100644 --- a/docs/references/react/use-clerk.mdx +++ b/docs/references/react/use-clerk.mdx @@ -1,20 +1,22 @@ --- title: '`useClerk()`' -description: Clerk's useClerk() hook is used to access the Clerk object, which can be used to build alternatives to any Clerk Component. +description: Access and manage the Clerk object in your React application with Clerk's useClerk() hook. --- -The `useClerk()` hook is a convenient way to access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, giving you the ability to build alternatives to any Clerk Component. - > [!WARNING] -> This is intended to be used for advanced use cases, like building a completely custom OAuth flow or as an escape hatch for getting access to the `Clerk` object. +> This composable should only be used for advanced use cases, such as building a completely custom OAuth flow or as an escape hatch to access to the `Clerk` object. + +The `useClerk()` hook provides access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, allowing you to build alternatives to any Clerk Component. -## `useClerk()` returns +## Returns The `useClerk()` hook returns the `Clerk` object, which includes all the methods and properties listed in the [`Clerk` reference](/docs/references/javascript/clerk/clerk). ## How to use the `useClerk()` hook -```tsx {{ filename: 'home.tsx' }} +The following example uses the `useClerk()` hook to access the `clerk` object. The `clerk` object is used to call the [`openSignIn()`](/docs/references/javascript/clerk/clerk#sign-in) method to open the sign-in modal. + +```tsx {{ filename: 'src/Home.tsx' }} import { useClerk } from '@clerk/clerk-react' export default function Home() { diff --git a/docs/references/react/use-organization-list.mdx b/docs/references/react/use-organization-list.mdx index 3381ed509b..dd611b8f63 100644 --- a/docs/references/react/use-organization-list.mdx +++ b/docs/references/react/use-organization-list.mdx @@ -1,11 +1,11 @@ --- title: '`useOrganizationList()`' -description: Clerk's useOrganizationList() hook is used to access methods for switching between active organizations and for listing the user's organization memberships, invitations, and suggestions. +description: Access and manage the current user's organization list in your React application with Clerk's useOrganizationList() hook. --- -The `useOrganizationList()` hook allows you to retrieve the organization memberships, invitations, or suggestions for an active user. It also provides methods for creating an organization and setting the active organization. +The `useOrganizationList()` hook provides access to the current user's organization memberships, invitations, and suggestions. It also includes methods for creating new organizations and managing the active organization. -## `useOrganizationList()` parameters +## Parameters `useOrganizationList()` accepts a single object with the following properties: @@ -84,7 +84,7 @@ type OrganizationSuggestionStatus = 'pending' | 'accepted' - `isLoaded` - `boolean` - A boolean is set to `false` until Clerk loads and initializes. Once Clerk loads, `isLoaded` will be set to `true`. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- @@ -215,7 +215,7 @@ const { userMemberships } = useOrganizationList({ The following example demonstrates how to use the `infinite` property to fetch and append new data to the existing list. The `userMemberships` attribute will be populated with the first page of the user's organization memberships. When the "Load more" button is clicked, the `fetchNext` helper function will be called to append the next page of memberships to the list. -```tsx {{ filename: 'app/components/JoinedOrganizations.tsx' }} +```tsx {{ filename: 'src/components/JoinedOrganizations.tsx' }} import { useOrganizationList } from '@clerk/clerk-react' import React from 'react' @@ -257,7 +257,7 @@ The following example demonstrates how to use the `fetchPrevious` and `fetchNext Notice the difference between this example's pagination and the infinite pagination example above. -```tsx {{ filename: 'app/components/UserInvitationsTable.tsx' }} +```tsx {{ filename: 'src/components/UserInvitationsTable.tsx' }} import { useOrganizationList } from '@clerk/clerk-react' import React from 'react' diff --git a/docs/references/react/use-organization.mdx b/docs/references/react/use-organization.mdx index 896510a0f2..a6ea31e0da 100644 --- a/docs/references/react/use-organization.mdx +++ b/docs/references/react/use-organization.mdx @@ -1,34 +1,76 @@ --- title: '`useOrganization()`' -description: Clerk's useOrganization() hook retrieves attributes of the currently active organization. +description: Access and manage the currently active organization in your React application with Clerk's useOrganization() hook. --- -The `useOrganization()` hook is used to retrieve attributes of the currently active organization. +The `useOrganization()` hook retrieves attributes of the currently active organization. -## `useOrganization()` parameters +## Parameters `useOrganization()` accepts a single object with the following optional properties: -| Properties | Description | -| - | - | -| `invitations?` | `true` or an object with [`status: OrganizationInvitationStatus`](#organization-invitation-status) or any of the properties described in [Shared properties](#shared-properties). If set to `true`, all default properties will be used. | -| `membershipRequests?` | `true` or an object with [`status: OrganizationInvitationStatus`](#organization-invitation-status) or any of the properties described in [Shared properties](#shared-properties). If set to `true`, all default properties will be used. | -| `memberships?` | `true` or an object with [`role: OrganizationCustomRoleKey[]`](#organization-custome-role-key) or any of the properties described in [Shared properties](#shared-properties). If set to `true`, all default properties will be used. | -| `domains?` | `true` or an object with [`enrollmentMode: OrganizationEnrollmentMode`](#organization-enrollment-mode) or any of the properties described in [Shared properties](#shared-properties). If set to `true`, all default properties will be used. | + + - `invitations` + - `true | { status?: OrganizationInvitationStatus } & { SharedProperties }` + + If set to `true`, all default properties will be used. Otherwise, accepts an object with an optional `status` property of type [`OrganizationInvitationStatus`](#organization-invitation-status) and any of the properties described in [Shared properties](#shared-properties). + + --- + + - `membershipRequests` + - `true | { status?: OrganizationInvitationStatus } & { SharedProperties }` + + If set to `true`, all default properties will be used. Otherwise, accepts an object with an optional `status` property of type [`OrganizationInvitationStatus`](#organization-invitation-status) and any of the properties described in [Shared properties](#shared-properties). + + --- + + - `memberships` + - `true | { role?: OrganizationCustomRoleKey[] } & { SharedProperties }` + + If set to `true`, all default properties will be used. Otherwise, accepts an object with an optional `role` property of type [`OrganizationCustomRoleKey[]`](#organization-custome-role-key) and any of the properties described in [Shared properties](#shared-properties). + + --- + + - `domains` + - `true | { enrollmentMode?: OrganizationEnrollmentMode } & { SharedProperties }` + + If set to `true`, all default properties will be used. Otherwise, accepts an object with an optional `enrollmentMode` property of type [`OrganizationEnrollmentMode`](#organization-enrollment-mode) and any of the properties described in [Shared properties](#shared-properties). + > [!WARNING] -> By default, the `memberships`, `invitations`, `membershipRequests`, and `domains` attributes are not populated. You must pass `true` or an object with the desired [properties](#shared-properties) to fetch and paginate the data. +> By default, the `memberships`, `invitations`, `membershipRequests`, and `domains` attributes aren't populated. You must pass `true` or an object with the desired [properties](#shared-properties) to fetch and paginate the data. ### Shared properties Properties that are shared across the `invitations`, `membershipRequests`, `memberships`, and `domains` properties. -| Properties | Description | -| - | - | -| `initialPage?` | A number that can be used to skip the first n-1 pages. For example, if `initialPage` is set to 10, it is will skip the first 9 pages and will fetch the 10th page. Defaults to `1`. | -| `pageSize?` | A number that indicates the maximum number of results that should be returned for a specific page. Defaults to `10`. | -| `keepPreviousData?` | If `true`, it will persist the cached data until the new data has been fetched. Defaults to `false`. | -| `infinite?` | If `true`, the new downloaded data will be appended to the list with the existing data. Ideal for infinite lists. Defaults to `false`. | + + - `initialPage` + - `number` + + A number that specifies which page to fetch. For example, if `initialPage` is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to `1`. + + --- + + - `pageSize` + - `number` + + A number that specifies the maximum number of results to return per page. Defaults to `10`. + + --- + + - `keepPreviousData` + - `boolean` + + If `true`, the previous data will be kept in the cache until new data is fetched. Defaults to `false`. + + --- + + - `infinite` + - `boolean` + + If `true`, newly fetched data will be appended to the existing list rather than replacing it. Useful for implementing infinite scroll functionality. Defaults to `false`. + ### `OrganizationInvitationStatus` @@ -62,13 +104,13 @@ type OrganizationEnrollmentMode = > [!NOTE] > These attributes are updating automatically and will re-render their respective components whenever you set a different organization using the [`setActive({ organization })`](/docs/references/javascript/clerk/session-methods#set-active) method or update any of the memberships or invitations. No need for you to manage updating anything manually. -## `useOrganization()` returns +## Returns - `isLoaded` - `boolean` - A boolean that is set to `false` until Clerk loads and initializes. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- @@ -115,28 +157,109 @@ type OrganizationEnrollmentMode = ### `PaginatedResources` -| Variables | Description | -| - | - | -| `data` | An array that contains the fetched data. | -| `count` | The total count of data that exist remotely. | -| `isLoading` | A boolean that is `true` if there is an ongoing request and there is no fetched data. | -| `isFetching` | A boolean that is `true` if there is an ongoing request or a revalidation. | -| `isError` | A boolean that indicates the request failed. | -| `page` | A number that indicates the current page. | -| `pageCount` | A number that indicates the total amount of pages. It is calculated based on `count` , `initialPage` , and `pageSize` | -| `fetchPage` | A function that triggers a specific page to be loaded. | -| `fetchPrevious` | A helper function that triggers the previous page to be loaded. This is the same as `fetchPage(page=> Math.max(0, page - 1))` | -| `fetchNext` | A helper function that triggers the next page to be loaded. This is the same as `fetchPage(page=> Math.min(pageCount, page + 1))` | -| `hasNextPage` | A boolean that indicates if there are available pages to be fetched. | -| `hasPreviousPage` | A boolean that indicates if there are available pages to be fetched. | -| `revalidate` | A function that triggers a revalidation of the current page. | -| `setData` | A function that allows you to set the data manually. | + + - `data` + - `any[]` + + An array that contains the fetched data. + + --- + + - `count` + - `number` + + The total count of data that exist remotely. + + --- + + - `isLoading` + - `boolean` + + A boolean that is `true` if there is an ongoing request and there is no fetched data. + + --- + + - `isFetching` + - `boolean` + + A boolean that is `true` if there is an ongoing request or a revalidation. + + --- + + - `isError` + - `boolean` + + A boolean that indicates the request failed. + + --- + + - `page` + - `number` + + A number that indicates the current page. + + --- + + - `pageCount` + - `number` + + A number that indicates the total amount of pages. It is calculated based on `count`, `initialPage`, and `pageSize`. + + --- + + - `fetchPage` + - `(page: number) => void` + + A function that triggers a specific page to be loaded. + + --- + + - `fetchPrevious` + - `() => void` + + A helper function that triggers the previous page to be loaded. This is the same as `fetchPage(page => Math.max(0, page - 1))`. + + --- + + - `fetchNext` + - `() => void` + + A helper function that triggers the next page to be loaded. This is the same as `fetchPage(page => Math.min(pageCount, page + 1))`. + + --- + + - `hasNextPage` + - `boolean` + + A boolean that indicates if there are available pages to be fetched. + + --- + + - `hasPreviousPage` + - `boolean` + + A boolean that indicates if there are available pages to be fetched. + + --- + + - `revalidate` + - `() => void` + + A function that triggers a revalidation of the current page. + + --- + + - `setData` + - `(data: any[]) => void` + + A function that allows you to set the data manually. + ## How to use the `useOrganization()` hook -### Expanding and paginating attributes +### Expand and paginate attributes -To keep network usage to a minimum, developers are required to opt-in by specifying which resource they need to fetch and paginate through. So by default, the `memberships`, `invitations`, `membershipRequests`, and `domains` attributes are not populated. You must pass `true` or an object with the desired [properties](#shared-properties) to fetch and paginate the data. +To keep network usage to a minimum, developers are required to opt-in by specifying which resource they need to fetch and paginate through. By default, the `memberships`, `invitations`, `membershipRequests`, and `domains` attributes are not populated. You must pass `true` or an object with the desired [properties](#shared-properties) to fetch and paginate the data. ```jsx // invitations.data will never be populated. diff --git a/docs/references/react/use-reverification.mdx b/docs/references/react/use-reverification.mdx index 5a804acb24..4361f3cd92 100644 --- a/docs/references/react/use-reverification.mdx +++ b/docs/references/react/use-reverification.mdx @@ -52,9 +52,9 @@ The `useReverification()` hook returns an array with the "enhanced" fetcher. The following example demonstrates how to handle scenarios where a user cancels the reverification flow, such as closing the modal, which might result in `myData` being `null`. -In this example, `myFetcher` would be a function in your backend that fetches data from the route that requires reverification. See the [guide on how to require reverification](/docs/guides/reverification) for more information. +In the following example, `myFetcher` would be a function in your backend that fetches data from the route that requires reverification. See the [guide on how to require reverification](/docs/guides/reverification) for more information. -```tsx {{ filename: 'MyButton.tsx' }} +```tsx {{ filename: 'src/components/MyButton.tsx' }} import { useReverification } from '@clerk/react' export function MyButton() { @@ -77,7 +77,7 @@ When `throwOnCancel` is set to `true`, the fetcher will throw a `ClerkRuntimeErr In this example, `myFetcher` would be a function in your backend that fetches data from the route that requires reverification. See the [guide on how to require reverification](/docs/guides/reverification) for more information. -```tsx {{ filename: 'MyButton.tsx' }} +```tsx {{ filename: 'src/components/MyButton.tsx' }} import { useReverification } from '@clerk/clerk-react' import { isClerkRuntimeError } from '@clerk/clerk-react/errors' diff --git a/docs/references/react/use-session-list.mdx b/docs/references/react/use-session-list.mdx index 85544e6c1e..6a81373bab 100644 --- a/docs/references/react/use-session-list.mdx +++ b/docs/references/react/use-session-list.mdx @@ -1,17 +1,17 @@ --- title: '`useSessionList()`' -description: Clerk's useSessionList() hook retrieves a list of sessions that have been registered on the client device. +description: Access and manage the current user's session list in your React application with Clerk's useSessionList() hook. --- The `useSessionList()` hook returns an array of [`Session`](/docs/references/javascript/session) objects that have been registered on the client device. -## `useSessionList()` returns +## Returns - `isLoaded` - `boolean` - A boolean that is set to `false` until Clerk loads and initializes. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- @@ -53,24 +53,24 @@ The `useSessionList()` hook returns an array of [`Session`](/docs/references/jav ## How to use the `useSessionList()` hook -The following example demonstrates how to use the `useSessionList()` hook to retrieve a list of sessions that have been registered on the client device. The `isLoaded` property is used to handle the loading state, and the `sessions` property is used to display the number of times the user has visited the page. +### Get a list of sessions -```tsx {{ filename: 'home.tsx' }} +The following example uses `useSessionList()` to get a list of sessions that have been registered on the client device. The `sessions` property is used to show the number of times the user has visited the page. + +```tsx {{ filename: 'src/Home.tsx' }} import { useSessionList } from '@clerk/clerk-react' export default function Home() { const { isLoaded, sessions } = useSessionList() if (!isLoaded) { - // handle loading state + // Handle loading state return null } + return (
-

- Welcome back. You have been here - {sessions.length} times before. -

+

Welcome back. You've been here {sessions.length} times before.

) } diff --git a/docs/references/react/use-session.mdx b/docs/references/react/use-session.mdx index d27b50f166..92c0f26ade 100644 --- a/docs/references/react/use-session.mdx +++ b/docs/references/react/use-session.mdx @@ -1,24 +1,24 @@ --- title: '`useSession()`' -description: Clerk's useSession() hook provides access to the the current user Session object, as well as helpers to set the active session. +description: Access and manage the current user's session in your React application with Clerk's useSession() hook. --- The `useSession()` hook provides access to the current user's [`Session`](/docs/references/javascript/session) object, as well as helpers for setting the active session. -## `useSession()` returns +## Returns - `isLoaded` - `boolean` - A boolean that is set to `false` until Clerk loads and initializes. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- - `isSignedIn` - `boolean` - A boolean that is set to `true` if the user is signed in. + A boolean that indicates whether a user is currently signed in. --- @@ -30,20 +30,22 @@ The `useSession()` hook provides access to the current user's [`Session`](/docs/ ## How to use the `useSession()` hook -The following example demonstrates how to use the `useSession()` hook to access the `SignIn` object, which has the `lastActiveAt` property on it. The `lastActiveAt` property is used to display the last active time of the current session to the user. +### Access the `Session` object -```tsx {{ filename: 'home.tsx' }} +The following example uses the `useSession()` hook to access the `Session` object, which has the `lastActiveAt` property. The `lastActiveAt` property is a `Date` object used to show the time the session was last active. + +```tsx {{ filename: 'src/Home.tsx' }} import { useSession } from '@clerk/clerk-react' export default function Home() { const { isLoaded, session, isSignedIn } = useSession() if (!isLoaded) { - // Add logic to handle loading state + // Handle loading state return null } if (!isSignedIn) { - // Add logic to handle not signed in state + // Handle signed out state return null } diff --git a/docs/references/react/use-sign-in.mdx b/docs/references/react/use-sign-in.mdx index aa194cb672..13c7b55668 100644 --- a/docs/references/react/use-sign-in.mdx +++ b/docs/references/react/use-sign-in.mdx @@ -1,17 +1,17 @@ --- title: '`useSignIn()`' -description: Clerk's useSignIn() hook provides access to the SignIn object, which allows you to check the current state of a sign-in. +description: Access and manage the current user's sign-in state in your React application with Clerk's useSignIn() hook. --- -The `useSignIn()` hook provides access to the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object, which allows you to check the current state of a sign-in. This is also useful for creating a [custom sign-in flow](#create-a-custom-sign-in-flow-with-use-sign-in). +The `useSignIn()` hook provides access to the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object, which allows you to check the current state of a sign-in attempt and manage the sign-in flow. You can use this to create a [custom sign-in flow](/docs/custom-flows/overview#sign-in-flow). -## `useSignIn()` returns +## Returns - `isLoaded` - `boolean` - A boolean that is set to `false` until Clerk loads and initializes. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- @@ -53,34 +53,63 @@ The `useSignIn()` hook provides access to the [`SignIn`](/docs/references/javasc ## How to use the `useSignIn()` hook -### Check the current state of a sign-in with `useSignIn()` +### Check the current state of a sign-in -Use the `useSignIn()` hook to check the current state of a sign-in. +The following example uses the `useSignIn()` hook to access the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state. -```tsx {{ filename: 'pages/sign-in-step.tsx' }} +```tsx {{ filename: 'src/pages/SignInPage.tsx' }} import { useSignIn } from '@clerk/clerk-react' -export default function SignInStep() { +export default function SignInPage() { const { isLoaded, signIn } = useSignIn() if (!isLoaded) { - // Add logic to handle loading state + // Handle loading state return null } - return
The current sign in attempt status is {signIn.status}.
+ return
The current sign-in attempt status is {signIn?.status}.
} ``` +### `SignIn` status values + The `status` property of the `SignIn` object can be one of the following values: -| Values | Descriptiom | -| - | - | -| `complete` | The user has been signed in and custom flow can proceed to `setActive()` to create session. | -| `needs_first_factor` | The first factor verification is missing. One of `email_link`, `email_code`, `phone_code`, `web3_metamask_signature`, `web3_coinbase_wallet_signature`, `web3_okx_wallet_signature` or `oauth_provider` is required to verify the user. See [the reference](/docs/references/javascript/sign-in/first-factor) for more information. | -| `needs_second_factor` | The Second Factor verification is missing. The Second Factor is an optional step to provide additional verification and includes `phone_code` and `totp`. See [Second Factor](/docs/references/javascript/sign-in/second-factor) for details. | -| `needs_identifier` | The user's identifier (email address, phone number, username, etc.) hasn't been provided. | -| `needs_new_password` | The user needs to set a new password. | + + - `complete` + - `string` + + The user has been signed in and the custom flow can proceed to `setActive()` to create a session. + + --- + + - `needs_first_factor` + - `string` + + One of the following [first factor verification strategies](/docs/references/javascript/sign-in/first-factor) is missing: `email_link`, `email_code`, `phone_code`, `web3_metamask_signature`, `web3_coinbase_wallet_signature` or `oauth_provider`. + + --- + + - `needs_second_factor` + - `string` + + One of the following [second factor verification strategies](/docs/references/javascript/sign-in/second-factor) is missing: `phone_code` or `totp`. + + --- + + - `needs_identifier` + - `string` + + The user's [identifier](/docs/authentication/configuration/sign-up-sign-in-options#identifiers) (e.g., email address, phone number, username) is missing. + + --- + + - `needs_new_password` + - `string` + + The user needs to set a new password. + ### Create a custom sign-in flow with `useSignIn()` diff --git a/docs/references/react/use-sign-up.mdx b/docs/references/react/use-sign-up.mdx index adceefd302..834054887d 100644 --- a/docs/references/react/use-sign-up.mdx +++ b/docs/references/react/use-sign-up.mdx @@ -1,17 +1,17 @@ --- title: '`useSignUp()`' -description: Clerk's useSignUp() hook gives you access to the SignUp object, which allows you to check the current state of a sign-up. +description: Access and manage the current user's sign-up state in your React application with Clerk's useSignUp() hook. --- -The `useSignUp()` hook gives you access to the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which allows you to check the current state of a sign-up. This is also useful for creating a [custom sign-up flow](#create-a-custom-sign-up-flow-with-use-sign-up). +The `useSignUp()` hook provides access to the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which allows you to check the current state of a sign-up attempt and manage the sign-up flow. You can use this to create a [custom sign-up flow](/docs/custom-flows/overview#sign-up-flow). -## `useSignUp()` returns +## Returns - `isLoaded` - `boolean` - A boolean that is set to `false` until Clerk loads and initializes. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- @@ -53,32 +53,49 @@ The `useSignUp()` hook gives you access to the [`SignUp`](/docs/references/javas ## How to use the `useSignUp()` hook -### Check the current state of a sign-up with `useSignUp()` +### Check the current state of a sign-up -Use the `useSignUp()` hook to access the `SignUp` object and check the current state of a sign-up. +The following example uses the `useSignUp()` hook to access the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which contains the current sign-up attempt status and methods to create a new sign-up attempt. The `isLoaded` property is used to handle the loading state. -```tsx {{ filename: 'sign-up-step.tsx' }} +```tsx {{ filename: 'src/pages/SignUpPage.tsx' }} import { useSignUp } from '@clerk/clerk-react' -export default function SignUpStep() { +export default function SignUpPage() { const { isLoaded, signUp } = useSignUp() if (!isLoaded) { - // Add logic to handle loading state + // Handle loading state return null } - return
The current sign-up attempt status is {signUp.status}.
+ return
The current sign-up attempt status is {signUp?.status}.
} ``` +### `SignUp` status values + The `status` property of the `SignUp` object can be one of the following values: -| Values | Description | -| - | - | -| `complete` | The user has been created and custom flow can proceed to `setActive()` to create session. | -| `abandoned` | The sign-up attempt will be abandoned if it was started more than 24 hours previously. | -| `missing_requirements` | A requirement from the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) settings is missing. For example, in the Clerk Dashboard, the password setting is required but a password was not provided in the custom flow. | + + - `complete` + - `string` + + The user has been created and the custom flow can proceed to `setActive()` to create a session. + + --- + + - `abandoned` + - `string` + + The sign-up attempt will be abandoned if it was started more than 24 hours previously. + + --- + + - `missing_requirements` + - `string` + + A requirement is missing from the [Email, Phone, Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) settings. For example, in the Clerk Dashboard, the **Password** setting is required but a password wasn't provided in the custom flow. + ### Create a custom sign-up flow with `useSignUp()` diff --git a/docs/references/react/use-user.mdx b/docs/references/react/use-user.mdx index af6bee5339..4c3b635bf0 100644 --- a/docs/references/react/use-user.mdx +++ b/docs/references/react/use-user.mdx @@ -1,49 +1,47 @@ --- title: '`useUser()`' -description: The useUser() hook is used to get the current user object and to update the user's data on the client-side. +description: Access and manage the current user's data in your React application with Clerk's useUser() hook. --- -The `useUser()` hook is a convenient way to access the current user's [`User`](/docs/references/javascript/user/user) object, which holds all of the information for a single user of your application and provides a set of methods to manage their account. This hook also provides boolean values to check if the user is signed in and if Clerk has loaded and initialized. +The `useUser()` hook provides access to the current user's [`User`](/docs/references/javascript/user/user) object, which contains all the data for a single user in your application and provides methods to manage their account. This hook also allows you to check if the user is signed in and if Clerk has loaded and initialized. -## `useUser()` returns +## Returns - - `isSignedIn` + - `isLoaded` - `boolean` - A boolean that returns `true` if the user is signed in. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- - - `isLoaded` + - `isSignedIn` - `boolean` - A boolean that until Clerk loads and initializes, will be set to `false`. Once Clerk loads, `isLoaded` will be set to `true`. + A boolean that returns `true` if the user is signed in. --- - `user` - - [`User`](/docs/references/javascript/user/user) + - [User](/docs/references/javascript/user/user) | null - The `User` object for the currently active user. If the user is not signed in, `user` will be `null`. + The `User` object for the current user. If the user isn't signed in, `user` will be `null`. ## How to use the `useUser()` hook -### Retrieve the current user data with the `useUser()` hook - -The following example demonstrates how to use the `useUser()` hook to access the `user` object, which includes the current user's data, like the user's full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively. +### Get the current user -For more information on the `User` object, see the [`reference`](/docs/references/javascript/user/user). +The following example uses the `useUser()` hook to access the [`User`](/docs/references/javascript/user/user) object, which contains the current user's data such as their full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively. -```tsx {{ filename: 'home.tsx' }} +```tsx {{ filename: 'src/Home.tsx' }} import { useUser } from '@clerk/clerk-react' export default function Home() { const { isSignedIn, user, isLoaded } = useUser() if (!isLoaded) { - // Handle loading state however you like + // Handle loading state return null } @@ -55,20 +53,18 @@ export default function Home() { } ``` -### Update the current user data with the `useUser()` hook +### Update user data -The following example demonstrates how to use the `useUser()` hook to access the `user` object, which includes the `update` method for updating the user's data. +The following example uses the `useUser()` hook to access the [`User`](/docs/references/javascript/user/user) object, which calls the [`update()`](/docs/references/javascript/user/user#update) method to update the current user's information. -For more information on the `update()` method, see the [`User`](/docs/references/javascript/user/user#update) reference. - -```tsx {{ filename: 'home.tsx' }} +```tsx {{ filename: 'src/Home.tsx' }} import { useUser } from '@clerk/clerk-react' export default function Home() { const { isLoaded, user } = useUser() if (!isLoaded) { - // Handle loading state however you like + // Handle loading state return null } @@ -83,7 +79,7 @@ export default function Home() { return ( <> - +

user.firstName: {user?.firstName}

user.lastName: {user?.lastName}

@@ -91,20 +87,18 @@ export default function Home() { } ``` -### Reload user data with the `useUser()` hook - -To retrieve the latest user data after updating the user elsewhere, use the `user.reload()` method. +### Reload user data -For more information on the `reload()` method, see the [`User`](/docs/references/javascript/user/user#reload) reference. +The following example uses the `useUser()` hook to access the [`User`](/docs/references/javascript/user/user) object, which calls the [`reload()`](/docs/references/javascript/user/user#reload) method to get the latest user's information via an external API endpoint. -```tsx {{ filename: 'home.tsx' }} +```tsx {{ filename: 'src/Home.tsx' }} import { useUser } from '@clerk/clerk-react' export default function Home() { const { isLoaded, user } = useUser() if (!isLoaded) { - // Handle loading state however you like + // Handle loading state return null } @@ -125,7 +119,7 @@ export default function Home() { return ( <> - +

user role: {user?.publicMetadata.role}

)