Merge branch 'main' into rob/eco-224-vue-sdk-references

clerk · Dec 19, 2024 · 5cf88b9 · 5cf88b9
2 parents 2aefa83 + 0635023
commit 5cf88b9
Show file tree

Hide file tree

Showing 61 changed files with 651 additions and 358 deletions.
diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/backend-requests/making/custom-session-token.mdx
@@ -24,18 +24,16 @@ This guide will show you how to customize a session token to include additional
 
   ## Use the custom claims in your application
 
-  The [`Auth`](/docs/references/nextjs/auth-object) object in the `@clerk/nextjs` package includes a `sessionClaims` property that contains the custom claims you added to your session token.
+  The [`Auth`](/docs/references/nextjs/auth-object) object includes a `sessionClaims` property that contains the custom claims you added to your session token. It's returned by the [`useAuth()`](/docs/references/react/use-auth) hook, the [`auth()`](/docs/references/nextjs/auth) and `getAuth()` helpers, and the `request` object in server contexts.
 
-  Access the custom claims in your application by calling `auth()` in App Router applications or `getAuth(req)` in Pages Router applications.
-
-  The following example demonstrates how to access the `fullName` and `primaryEmail` claims that were added to the session token in the last step.
+  The following example demonstrates how to access the `fullName` and `primaryEmail` claims that were added to the session token in the last step. This examples are written for Next.js, but they can be adapted to other frameworks by using the appropriate method for accessing the `Auth` object.
 
   <CodeBlockTabs options={["App Router", "Pages Router"]}>
-    ```tsx {{ filename: 'app/page.tsx' }}
+    ```tsx {{ filename: 'app/api/example/route.tsx' }}
     import { auth } from '@clerk/nextjs/server'
     import { NextResponse } from 'next/server'
 
-    export default async function Page() {
+    export async function GET() {
       const { sessionClaims } = await auth()
 
       const fullName = sessionClaims?.fullName

diff --git a/docs/quickstarts/expo.mdx b/docs/quickstarts/expo.mdx
@@ -176,7 +176,7 @@ description: Add authentication and user management to your Expo app with Clerk.
      export const tokenCache = Platform.OS !== 'web' ? createTokenCache() : undefined
      ```
   1. Update your root layout to use the token cache:
-     ```tsx {{ filename: 'app/_layout.tsx', mark: [3, 13] }}
+     ```tsx {{ filename: 'app/_layout.tsx', mark: [1, 13] }}
      import { tokenCache } from '@/cache'
      import { ClerkProvider, ClerkLoaded } from '@clerk/clerk-expo'
      import { Slot } from 'expo-router'

diff --git 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.
 </Properties>
 
 ## How to use the `$authStore` store

diff --git 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<Invitation>
   ---
 
   - `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
@@ -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.
 </Properties>
 
 ## Example

diff --git 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
@@ -36,14 +36,14 @@ function createOrganization(params: CreateParams): Promise<Organization>
   ---
 
   - `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
@@ -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.
 </Properties>
 
 ## Example

diff --git 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' }}.
 </Properties>

diff --git 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
@@ -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' }}.
 </Properties>

diff --git 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<Organizat
   ---
 
   - `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. Updating this property will override the existing metadata. To merge metadata, use [`updateOrganizationMetadata()`](/docs/references/backend/organization/update-organization-metadata).
 
   ---
 
   - `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' }}.
+  Metadata that is only visible to your [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. Updating this property will override the existing metadata. To merge metadata, use [`updateOrganizationMetadata()`](/docs/references/backend/organization/update-organization-metadata).
 
   ---
 

diff --git a/docs/references/backend/sign-in-tokens/create-sign-in-token.mdx b/docs/references/backend/sign-in-tokens/create-sign-in-token.mdx
@@ -15,7 +15,7 @@ function createSignInToken(params: CreateSignInTokensParams): Promise<SignInToke
   - `userId`
   - `string`
 
-  The ID of the user that can use the newly created sign in token
+  The ID of the user who can use the newly created sign-in token.
 
   ---
 

diff --git a/docs/references/backend/types/backend-allowlist-identifier.mdx b/docs/references/backend/types/backend-allowlist-identifier.mdx
@@ -25,14 +25,14 @@ The Backend `AllowlistIdentifier` object represents an identifier that has been
   - `createdAt`
   - `number`
 
-  Date when the allowlist identifier was first created.
+  The date when the allowlist identifier was first created.
 
   ---
 
   - `updatedAt`
   - `number`
 
-  Date of the last time the allowlist identifier was updated.
+  The date when the allowlist identifier was last updated.
 
   ---
 

diff --git a/docs/references/backend/types/backend-client.mdx b/docs/references/backend/types/backend-client.mdx
@@ -11,7 +11,7 @@ The Backend `Client` object is similar to the [`Client`](/docs/references/javasc
   - `id`
   - `string`
 
-  A unique identifier for the client.
+  The unique identifier for the `Client`.
 
   ---
 
@@ -53,12 +53,12 @@ The Backend `Client` object is similar to the [`Client`](/docs/references/javasc
   - `createdAt`
   - `number`
 
-  Date when the `Client` was first created.
+  The date when the `Client` was first created.
 
   ---
 
   - `updatedAt`
   - `number`
 
-  Date of the last time the `Client` was updated.
+  The date when the `Client` was last updated.
 </Properties>
diff --git 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
@@ -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' }}.
 </Properties>
diff --git 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.
 
   ---