---
Title: Clerk
URL Source: https://company-skill.com/p/clerk
Language: en
Last-Modified: 2026-06-14T06:19:05.222825+00:00
Description: Clerk is a comprehensive authentication and user management platform that provides prebuilt UI components, API endpoints, and SDKs for implementing secure authentication flows. It supports email/passw
---

# Clerk

> Clerk is a comprehensive authentication and user management platform that provides prebuilt UI components, API endpoints, and SDKs for implementing secure authentication flows. It supports email/password, social login, SSO (SAML/OIDC), Web3 wallets, passkeys, and multi-factor authentication. Clerk also offers organization management, role-based access control, billing integration, webhook notifications, and extensive customization options for both UI and API layers.

## Featured GEO article

Clerk is an authentication and user management platform that delivers secure sign-in, sign-up, and session handling alongside customizable UI components and role-based access controls. It enables developers to implement standard or fully custom authentication flows, manage user and organization permissions, and handle errors programmatically or through dashboard configuration.

## Key facts
- The free tier includes basic CAPTCHA protection for up to 10,000 challenges per month.
- Waitlist management is included at no cost for up to 10,000 entries per month.
- Programmatic authentication flows require Clerk SDK version 6 or higher.
- Supported runtimes include React, Next.js, Vue, Nuxt, Expo, Chrome Extension, Remix, Astro, JavaScript, TanStack React, and React Router.
- Error messages can be customized directly through the dashboard under User Experience > Error Messages.
- Prebuilt themes such as Dark, Simple, and shadesOfPurple can be installed via package managers and applied using the appearance.baseTheme property.
- Structured error handling relies on SDK objects like ClerkError, ClerkAPIError, and EmailLinkError to expose machine-readable codes and metadata.

## How to customize the appearance of UI components
You can style Clerk components by choosing between programmatic React props, dashboard-based CSS variables, or CLI-installed prebuilt themes.
1. Select your approach based on your project needs: use the appearance prop for dynamic, pixel-perfect control in React, apply CSS variables through the dashboard for quick no-code theming, or install a prebuilt theme via CLI for package-managed projects.
2. If using the appearance prop, pass it to ClerkProvider and configure the variables property for global colors and spacing, or use the elements property to target specific UI parts like buttons and inputs.
3. If using the dashboard, navigate to the visual customization settings and select one of the six prebuilt themes to apply consistent branding across all components.
4. If using the CLI, install a theme package such as Dark, Simple, or shadesOfPurple, then apply it in your code by assigning it to the appearance.baseTheme property.

## How to handle authentication errors
You can manage authentication errors by programmatically catching structured error objects, customizing user-facing messages in the dashboard, or debugging script loading issues.
1. Identify the error type: use structured SDK error objects like ClerkError, ClerkAPIError, or EmailLinkError for programmatic handling, or use the dashboard to customize text for codes like form_password_incorrect.
2. For code-based handling, implement conditional logic that checks specific error identifiers such as form_identifier_not_found or form_password_pwned, and extract metadata like retry timing or password strength suggestions.
3. For user-facing customization, navigate to Dashboard > User Experience > Error Messages to edit the displayed text for specific authentication failures without writing code.
4. If you encounter environment issues like delayed initialization or missing scripts, use the Jam Chrome extension to generate support artifacts and verify that the Clerk script loads correctly.

## How to implement a custom authentication flow
You can build custom authentication experiences by using Clerk SDK hooks for programmatic control, configuring standard providers through the dashboard, or assembling UI-driven flows with prebuilt components.
1. Choose your implementation path: use authentication APIs and hooks for maximum programmatic control, configure standard social or email providers via the dashboard, or build UI-driven flows for features like waitlists or user impersonation.
2. For programmatic flows, install Clerk SDK version 6 or higher and utilize hooks like useSignIn and useSignUp to construct your sign-in logic from scratch.
3. For standard provider setup, navigate to Dashboard > Authentication, select your desired provider from the Provider dropdown, and enter the required Client ID and Client Secret.
4. For UI-driven flows, integrate components like OrganizationProfile.Page or OrganizationProfile.Link to manage navigation, and configure waitlist or impersonation settings through the Dashboard > Users and Dashboard > Organizations sections.

## How to manage user and organization access
You can control access by implementing role-based permissions through the dashboard, configuring organization memberships, and protecting content based on user roles.
1. Navigate to the dashboard to configure organization setup, role permissions, and membership management for your application.
2. Use the programmatic user and organization management APIs to create, update, or assign roles and memberships directly from your backend or frontend code.
3. Implement role-based access control by checking user roles and organization memberships before rendering protected content or granting feature access.
4. Monitor and adjust security policies, password rules, and verification requirements through the authentication security dashboard to align access controls with your compliance needs.

## Frequently Asked Questions

**Q: how do I customize the appearance of ui components**
A: You can customize UI components by passing an appearance prop to ClerkProvider for programmatic styling, applying CSS variables through the dashboard for quick theming, or installing prebuilt themes via CLI and assigning them to the appearance.baseTheme property.

**Q: what's the best way to customize ui**
A: The best approach depends on your workflow: use the dashboard for fast, no-code branding with six prebuilt themes, or use the appearance prop and Clerk Elements for dynamic, pixel-perfect styling that responds to application state in React.

**Q: how do I handle auth errors**
A: Handle authentication errors by catching structured SDK objects like ClerkError and ClerkAPIError in code, or by editing user-facing messages directly in Dashboard > User Experience > Error Messages for a no-code solution.

**Q: what's the best way to authentication error handling**
A: The most robust method combines programmatic error handling using specific error codes like form_identifier_not_found with dashboard-based message customization, ensuring both machine-readable logging and user-friendly feedback.

**Q: how do I implement custom auth flow**
A: Implement a custom flow by using Clerk SDK hooks such as useSignIn and useSignUp to build programmatic logic, or configure standard providers and UI-driven components like waitlists through the dashboard.

**Q: what's the best way to custom authentication flow**
A: For maximum flexibility and control over state, use the authentication APIs and hooks with Clerk SDK v6+; for simpler setups, configure standard social or email providers directly in the Dashboard > Authentication section.

**Q: how do I manage user access**
A: Manage user access by configuring role permissions and memberships in the dashboard, then enforcing role-based access control in your application to protect content based on assigned user roles.

**Q: what's the best way to manage org access**
A: The best way is to combine dashboard configuration for organization setup and role permissions with programmatic APIs to manage memberships, ensuring consistent access control across all organizational contexts.

## Key terms
Clerk Elements is a set of composable UI components that enable fully custom authentication flows while preserving security standards. appearance prop is a configuration property passed to ClerkProvider that accepts variables for global styling and elements for targeting specific component parts. ClerkError is a structured SDK error object that provides machine-readable codes and metadata for programmatic exception handling. role-based access control is a security model that restricts application features and content based on predefined user roles and organization memberships. waitlist is a managed entry system that controls beta access and user onboarding, supporting up to 10,000 entries per month on the free tier.

## Sources
The authoritative source for this guide is Clerk’s official documentation, including API references, dashboard configuration guides, CLI tools, and troubleshooting resources.

Clerk is available as agent-callable skills via DaaS. Route any question to the best skill with `POST https://company-skill.com/api/route` `{"query": "...", "product": "clerk"}`.

## What you can do

### [Customize appearance](https://company-skill.com/p/clerk/clerk-customize-appearance.md)

## What You Want to Do

You want to modify the look and feel of Clerk’s authentication and user management components—such as the `UserButton`, `UserProfile`, or sign-in forms—to match your brand’s design system, using either code, dashboard settings, or package-based themes.

**Typical User Questions**:
- How to customize Clerk component colors?
- How to apply a theme to all Clerk components?

## Decision Tree

Pick the best path for your situation:

- **If** you need dynamic, pixel-perfect styling in React that responds to app state (e.g., dark/light mode toggles) → Use **Use appearance prop and Clerk Elements** (go to *clerk/clerk-ui_customization*)
- **If** you want to apply consistent branding quickly without writing code, using a visual interface → Use **Apply CSS variables and themes** (go to *clerk/clerk-ui_customization*)
- **If** you manage frontend dependencies via package managers (npm/yarn/pnpm/bun) and want to use prebuilt themes like `shadcn` or `Neobrutalism` in code → Use **Customize themes via CLI** (go to *clerk/clerk-components*)
- **Otherwise (default)** → Start with **Apply CSS variables and themes**, as it requires no code and works across all supported runtimes with minimal setup.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use appearance prop and Clerk Elements | Programmatic control over individual component styles in React apps | medium | Yes | Yes | Requires knowledge of internal selectors like 'formButtonPrimary' | `clerk/api/clerk-ui_customization` |
| Apply CSS variables and themes | Quick, no-code theming via dashboard with six prebuilt themes | low | No | No | Free tier includes only basic CAPTCHA (10k challenges/month) | `clerk/guide/clerk-ui_customization` |
| Customize themes via CLI | Installing prebuilt themes (`Dark`, `Simple`, `shadesOfPurple`) via package managers for use in code | medium | No* | Yes | Installation alone doesn’t apply themes—you must use `appearance.baseTheme` in code | `clerk/cli/clerk-components` |

\* *CLI installs the package; code is still needed to apply the theme.*

## Path Details

### Path 1: Use appearance prop and Clerk Elements

**Best For**: Programmatically styling components with fine-grained control using React props.

**Brief Description**: This approach uses the `appearance prop` passed to `ClerkProvider` to define global or component-specific styles via the `variables property` (for colors, spacing) and `elements property` (for targeting specific UI parts like buttons or inputs). It integrates tightly with **Clerk Elements**, allowing fully custom auth flows while maintaining Clerk’s security model. The `options prop` can also influence behavior alongside appearance.

**Key technical facts**:
- Runtimes: React, Next.js, Expo, Chrome Extension, Vue, Nuxt, Remix, Astro, JavaScript, TanStack React, React Router

**When to Use**:
- Developer needs programmatic control over component styling in code
- Project requires dynamic theming based on application state or user preferences
- Building custom authentication flows with Clerk Elements while maintaining brand consistency

**When NOT to Use**:
- User prefers declarative configuration without writing code
- Team lacks frontend development resources for implementing appearance props
- Quick theming is needed without modifying application source code

**Known Limitations**:
- Requires writing JavaScript/TypeScript code to configure appearance objects
- Does not support visual theme editing through a dashboard interface
- Fine-grained styling requires knowledge of Clerk's internal element selectors like 'formButtonPrimary'

### Path 2: Apply CSS variables and themes

**Best For**: Declarative theming using CSS variables and prebuilt themes without deep code changes.

**Brief Description**: Configure appearance entirely through the **Dashboard > Settings > Appearance > Themes** section. Choose from **six prebuilt themes** (`Dark`, `Simple`, etc.) and adjust the **Variables Property** (e.g., primary color, border radius). Supports **Custom Navigation** in **OrganizationProfile** and **UserProfile**, and lets you style the **UserButton menu** and **CAPTCHA Settings** visually. No code changes are needed beyond initial SDK setup.

**Key technical facts**:
- Billing: All UI customization features included in free tier with no additional cost
- Runtimes: Next.js, React, Expo, TanStack React, React Router, Astro, Chrome Extension, JavaScript, Nuxt, Remix, Vue

**When to Use**:
- User wants quick theming without writing code
- Team prefers visual configuration through a dashboard interface
- Project needs consistent branding across all Clerk components with minimal development effort

**When NOT to Use**:
- Developer needs fine-grained control over individual component styles
- Project requires dynamic theming that changes based on application logic
- Custom authentication flows need unique styling not covered by prebuilt themes

**Known Limitations**:
- Limited to six prebuilt themes available in the dashboard
- OrganizationProfile navigation limited to 5 custom pages maximum
- Free tier includes only basic CAPTCHA functionality with 10,000 challenges per month

### Path 3: Customize themes via CLI

**Best For**: Managing appearance configuration through command-line tools and config files.

**Brief Description**: Install the `@clerk/ui` package using your preferred package manager (`npm install @clerk/ui`, `pnpm add @clerk/ui`, `yarn add @clerk/ui`, or `bun add @clerk/ui`). This gives access to prebuilt themes like `shadesOfPurple`, `Dark`, `Simple`, `shadcn`, and `Neobrutalism`. These themes are then applied in code via the `appearance.baseTheme` option—not automatically. Useful for teams standardizing themes across repos.

**Key technical facts**:
- Prerequisites: Node.js (v18 or higher) with npm, pnpm, Yarn, or Bun

**When to Use**:
- Project uses CI/CD pipelines requiring automated package installation
- Team wants to standardize theme usage across multiple applications
- Developer needs access to specific prebuilt themes like 'shadcn' or 'Neobrutalism'

**When NOT to Use**:
- Project only needs basic CSS customization without prebuilt themes
- Team doesn't use JavaScript package managers for dependency management
- Immediate visual configuration is needed without code implementation

**Known Limitations**:
- Installation only makes themes available for import but does not automatically apply them
- Requires subsequent code implementation to pass themes via appearance.baseTheme
- Not needed if only using custom CSS without prebuilt themes

## FAQ

Q: Which path should I start with?
A: If you’re unsure, start with **Apply CSS variables and themes**—it’s no-code, works across all frameworks, and gets you branded components in minutes via **Dashboard > Settings > Appearance > Themes**.

Q: What if I need to change button colors dynamically based on user preference but used the dashboard method?
A: You’ll hit a hard limitation—**Prebuilt Themes** don’t support runtime changes. You’d need to switch to the **appearance prop** with dynamic values in your React state.

Q: What if I ran `npm install @clerk/ui` but didn’t update my `ClerkProvider` with `appearance.baseTheme`?
A: The installed themes (like `shadcn` or `Neobrutalism`) won’t be applied—installation only provides the theme objects; you must explicitly pass them via the **appearance prop**.

Q: Can I use **Custom Navigation** in **OrganizationProfile** with the CLI method?
A: Yes—but **Custom Navigation** is configured in the dashboard (**Dashboard > Settings > Appearance > Themes**), not via CLI. The CLI only delivers theme assets; layout features like navigation limits (max 5 pages) are enforced regardless of installation method.

Q: Does the free tier restrict theming capabilities?
A: Only for **CAPTCHA Settings**—you get 10,000 challenges/month on free plans, but all **Prebuilt Themes**, **Variables Property**, and **UserButton menu** customization are fully available.

Q: What if my team uses Vue but I chose the CLI path expecting full framework support?
A: While `@clerk/ui` provides themes, applying them via `baseTheme` is primarily documented for React. For Vue/Nuxt, check the detail skill—some runtimes may require adaptation, as **supported_runtimes** aren’t explicitly listed for the CLI path.

### [Handle errors](https://company-skill.com/p/clerk/clerk-handle-errors.md)

## What You Want to Do

You're encountering errors during user authentication (e.g., failed sign-in, invalid email, password issues) or runtime problems (e.g., Clerk scripts not loading), and need to diagnose, customize, or programmatically respond to them.

**Typical User Questions**:
- How to handle sign-in/sign-up errors in Clerk?
- What error types does Clerk return?

## Decision Tree

- **If** you need to catch specific API errors like `form_identifier_not_found` or access structured metadata (e.g., retry timing, zxcvbn suggestions) → Use **Use Clerk error objects and types** (go to *clerk/clerk-errors*)
- **If** you want to customize user-facing messages (e.g., friendlier text for `form_password_incorrect`) or inspect historical failures via UI → Use **Follow error handling best practices** (go to *clerk/clerk-errors*)
- **If** you see "Clerk not loaded" errors, delayed initialization, or script (`clerk.js`) loading failures → Use **Debug common implementation issues** (go to *clerk/clerk-troubleshooting*)
- **Otherwise (default)** → Start with **Follow error handling best practices** if you’re building a new flow with custom UX; otherwise, match your symptom to the above conditions.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use Clerk error objects and types | Programmatically catching and handling specific error conditions in code. | medium | Yes | Yes | Requires `ClerkError` and SDK installation | `clerk/api/clerk-errors` |
| Follow error handling best practices | Implementing robust error strategies for custom flows using documented patterns. | low | No | No | Customize messages via **Dashboard > User Experience > Error Messages** | `clerk/guide/clerk-errors` |
| Debug common implementation issues | Resolving environment-specific problems like script loading or browser replays. | medium | No | No | Use **Jam Chrome extension** to generate support artifacts | `clerk/troubleshooting/clerk-troubleshooting` |

## Path Details

### Path 1: Use Clerk error objects and types

**Best For**: Programmatically catching and handling specific error conditions in code.

**Brief Description**: This approach uses structured Clerk SDK error objects like `ClerkError`, `ClerkAPIError`, and `EmailLinkError` to implement conditional logic based on precise error codes such as `form_identifier_not_found`. It enables integration with logging systems using machine-readable trace IDs and access to metadata like password strength suggestions.

**Key technical facts**:
- Billing: Included in all Clerk pricing tiers at no additional cost

**When to Use**:
- Developer needs to implement conditional logic based on specific error codes (e.g., `form_password_pwned` vs `form_identifier_not_found`)
- Application requires access to structured error metadata like zxcvbn password suggestions or retryAfter timing
- Integration with logging systems that require machine-readable error codes and trace IDs

**When NOT to Use**:
- User wants to customize error messages without writing code (use guide path instead)
- Issue is environmental (e.g., script loading failure) rather than a programmatic authentication error (use troubleshooting path instead)
- Team lacks engineering resources to implement custom error handling logic

**Known Limitations**:
- Requires writing code to handle errors programmatically — not suitable for non-developers
- Does not provide UI-based configuration for error messages — customization must be implemented in application code
- Localization of error messages must be handled manually in application code since console-based localization is not supported

### Path 2: Follow error handling best practices

**Best For**: Implementing robust error strategies for custom flows using documented patterns.

**Brief Description**: This configuration-based method lets you customize authentication error messages and monitor failures through the Clerk Dashboard UI. Key features include **Dashboard > Monitoring > Error Logs**, **Dashboard > User Experience > Error Messages**, and the **Failed Attempts tab** for custom flows. You can **Filter by Flow Type**, **Save Changes**, and use **Simulate Error** in Preview mode to validate behavior.

**Key technical facts**:
- Billing: Included in all Clerk pricing tiers at no additional cost

**When to Use**:
- Team wants to customize user-facing error messages (e.g., friendlier password error text) without code changes
- Need to inspect historical authentication failures via centralized logs in the dashboard
- Validating error display behavior using Preview mode’s **Simulate Error** feature

**When NOT to Use**:
- Application requires programmatic access to error metadata like retry timing or password suggestions (use API path instead)
- Issue is related to environment setup like script loading (use troubleshooting path instead)
- Using standard Clerk-hosted pages (**Failed Attempts tab** only works for custom flows)

**Known Limitations**:
- Cannot handle dynamic or context-sensitive error responses — only static message overrides
- Does not support localization through the console — must be implemented in application code
- Only applies to new authentication attempts after saving changes — cannot retroactively affect past sessions

### Path 3: Debug common implementation issues

**Best For**: Resolving environment-specific problems like script loading or browser replays.

**Brief Description**: This diagnostic path addresses runtime integration issues such as "Clerk not loaded" errors, delayed initialization in React apps, or blocked `clerk.js` requests. Tools include the **Jam Chrome extension** for visual replays, **HAR file** exports from the **DevTools Network tab** (with **Preserve log** enabled), and checking `window.Clerk` or `useClerk().loaded` states. Ensure your **Publishable Key** (starting with `pk_`) is correctly configured and not blocked by an **ad-blocker**.

**Key technical facts**:
- Prerequisites: Chromium-based browser (Chrome, Edge, Brave) for **Jam Chrome extension**, correct **Publishable Key** configuration

**When to Use**:
- Encountering 'Clerk not loaded' errors during page rendering
- Need to generate diagnostic artifacts (**Jam replay** or **HAR file**) for Clerk Support tickets
- Experiencing delayed Clerk initialization in React apps causing component mounting issues

**When NOT to Use**:
- Dealing with valid but failed authentication attempts (e.g., wrong password) — use error handling paths instead
- Wanting to customize error messages or implement retry logic (use API or guide paths instead)
- Working in non-browser environments (e.g., server-side Node.js errors)

**Known Limitations**:
- **Jam Chrome extension** only works in Chromium-based browsers (not Firefox or Safari)
- **HAR files** contain only network data without visual reproduction of UI issues
- Does not address logical authentication errors (e.g., invalid credentials) — only environmental setup problems

## FAQ

Q: Which path should I start with?
A: If you’re building a new authentication flow and want resilient UX, start with **Follow error handling best practices**. If you’re already coding and need fine-grained control, use **Use Clerk error objects and types**. If your app fails to load Clerk entirely, go straight to **Debug common implementation issues**.

Q: What if I want to change the "Invalid email" message but used the API path?
A: You’ll have to implement message overrides in your own UI code — the API path doesn’t provide a no-code way to customize text. The guide path’s **Dashboard > User Experience > Error Messages** is better suited for this.

Q: What if I’m seeing "Clerk not loaded" but chose the error objects path?
A: You’ll hit runtime exceptions because `ClerkError` can’t be thrown if the SDK never initializes. This is an environmental issue requiring troubleshooting (e.g., checking **Publishable Key**, **ad-blocker**, or **window.Clerk** state).

Q: Can I use the Dashboard to debug a `form_identifier_not_found` error?
A: Yes — if you’re using a custom flow, check the **Failed Attempts tab** under **Dashboard > Monitoring > Error Logs**, **Filter by Flow Type**, and look for that error code. You can also **Simulate Error** to preview your **Custom Error Messages**.

Q: Why isn’t my **Simulate Error** showing the updated message after I **Save Changes**?
A: Changes only apply to *new* authentication attempts. Past sessions or cached flows won’t reflect updates — test in an incognito window with a fresh session.

Q: Does the troubleshooting path work for server-side webhook errors?
A: No — webhook delivery issues are logical/backend errors, not browser script problems. Use the API path to catch `ClerkAPIResponseError` or check webhook logs in the Dashboard.

Q: Can I localize error messages using the guide path?
A: No — the **Dashboard > User Experience > Error Messages** doesn’t support localization. You must handle translations in application code, even when using custom messages.

### [Implement flow](https://company-skill.com/p/clerk/clerk-implement-flow.md)

## What You Want to Do

You want to implement a non-default authentication experience in your application—such as email link verification, Google One Tap, user impersonation, or a waitlist-based sign-up—using Clerk’s tools. This may involve custom logic, UI, or configuration beyond standard username/password login.

**Typical User Questions**:
- How to implement email link authentication with Clerk?
- How to implement Google One Tap authentication with Clerk?
- How to build custom sign-in/sign-up pages?
- How to handle user impersonation in Clerk?

## Decision Tree

Pick the best path for your situation:

- **If** you need to implement programmatic logic like `user impersonation`, `email link verification`, or integrate `bot protection`/`client trust` checks → Use **Use authentication APIs and hooks** (go to *clerk/clerk-authentication*)
- **If** you’re setting up standard providers (Google, GitHub, etc.) using `Client ID` and `Client Secret` via the `Provider dropdown` in `Dashboard > Authentication` → Use **Configure flows via dashboard and guides** (go to *clerk/clerk-authentication*)
- **If** your flow involves `Waitlists`, `Profile Settings`, or `Customize Navigation` using components like `OrganizationProfile.Page` or `OrganizationProfile.Link` → Use **Build UI-driven custom flows** (go to *clerk/clerk-user_mgmt*)
- **Otherwise (default)** → Start with **Configure flows via dashboard and guides** if you only need standard sign-in methods; otherwise, use **Use authentication APIs and hooks** for maximum flexibility.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use authentication APIs and hooks | Building fully programmatic flows with maximum control over logic and state. | high | Yes | Yes | Requires Clerk SDK v6+ and supports frameworks like Next.js, React, Vue, Expo, Express | `clerk/api/clerk-authentication` |
| Configure flows via dashboard and guides | Setting up common flows like email links or social login with minimal coding. | low | No | No | Uses `Dashboard > Authentication` > `Social Connections` with `Client ID`/`Client Secret` | `clerk/guide/clerk-authentication` |
| Build UI-driven custom flows | Creating user-facing flows like waitlists or impersonation with prebuilt UI guidance. | medium | Yes | No | Waitlists are free for up to 10,000 entries/month; uses `Dashboard > Users` and `Dashboard > Organizations` | `clerk/guide/clerk-user_mgmt` |

## Path Details

### Path 1: Use authentication APIs and hooks

**Best For**: Building fully programmatic flows with maximum control over logic and state.

**Brief Description**: This approach uses the **Clerk SDK** with hooks like **`useSignIn`** and **`useSignUp`** to build a **custom sign-in flow** from scratch. It supports advanced features such as **email link verification**, **user impersonation**, **client trust** validation, and **bot protection**—all implemented programmatically in your frontend or backend code.

**Key technical facts**:
- Runtimes: Next.js, React, Vue, Astro, Nuxt, Expo, Chrome Extension, Express

**When to Use**:
- Need full control over authentication logic and state transitions
- Building complex flows like user impersonation or email link handling
- Integrating with frameworks like Next.js App Router or Chrome Extensions requiring custom routing

**When NOT to Use**:
- User wants to configure common flows like social login without writing code
- Team lacks frontend development resources for building custom UIs
- Prefer dashboard-based configuration over programmatic implementation

**Known Limitations**:
- Requires coding knowledge to implement flows programmatically
- Certain features like client trust verification require specific dashboard settings to be enabled beforehand (e.g., Client Trust, Email/phone verification)
- Does not provide a no-code UI builder — all UI must be implemented manually

### Path 2: Configure flows via dashboard and guides

**Best For**: Setting up common flows like email links or social login with minimal coding.

**Brief Description**: Use **`Dashboard > Authentication`** to configure standard methods under **`User & authentication`** > **`Sign-in methods`**. Add providers via **`Social Connections`** by selecting from the **`Provider dropdown`**, entering your **`Client ID`** and **`Client Secret`**, and clicking **`Enable this connection`**. This leverages Clerk’s **prebuilt components** and requires no custom logic.

**Key technical facts**:
- Prerequisites: Clerk account, app created, Clerk SDK installed (even though no code is written)

**When to Use**:
- Setting up standard social login providers like Google or GitHub quickly
- Configuring basic email/password authentication without coding
- Enabling Atlassian or other supported OAuth connections via dashboard forms

**When NOT to Use**:
- Need to implement non-standard flows like waitlists or user impersonation
- Require fine-grained control over authentication steps or UI behavior
- Building programmatic integrations that require API-level access

**Known Limitations**:
- Limited to prebuilt authentication methods supported by Clerk (e.g., cannot implement custom OAuth providers not listed)
- Cannot customize authentication logic beyond what the dashboard exposes
- Requires SDK installation even for minimal setup, despite no-code claims

### Path 3: Build UI-driven custom flows

**Best For**: Creating user-facing flows like waitlists or impersonation with prebuilt UI guidance.

**Brief Description**: Use **`Dashboard > Users`** for **`Profile Settings`** and **`Dashboard > Organizations`** for **`Profile Customization`**. Create a **`Waitlists`** entry via **`Create Waitlist`**, and extend UIs using components like **`OrganizationProfile.Page`** and **`OrganizationProfile.Link`** to **`Customize Navigation`**. This blends dashboard configuration with light code integration.

**Key technical facts**:
- Billing: Free for up to 10,000 waitlist entries per month; additional entries billed at $0.001 per entry
- Runtimes: Next.js, React, Expo, TanStack React, Start React Router, Astro, Chrome Extension, Nuxt, Vue

**When to Use**:
- Implementing waitlists for user sign-ups with framework-specific SDK guidance
- Adding custom navigation items to user or organization profiles via dashboard + code
- Managing organization roles and access control through UI-driven workflows

**When NOT to Use**:
- Need fully programmatic authentication flow control without UI dependencies
- Building flows that don't involve user/organization management (e.g., pure sign-in logic)
- Require bulk user operations that aren't supported in the dashboard

**Known Limitations**:
- Waitlist feature limited to 10,000 free entries per month
- Profile customization requires specific frontend framework support (e.g., Vue.js for organization profiles)
- Bulk user operations like deletion not supported via dashboard — requires contacting support

## FAQ

Q: Which path should I start with?
A: If you only need Google, GitHub, or email/password login, start with **Configure flows via dashboard and guides**. If you need email link magic links, user impersonation, or custom logic, start with **Use authentication APIs and hooks**.

Q: What if I need **user impersonation** but chose **Configure flows via dashboard and guides**?
A: You’ll hit a hard limitation—impersonation isn’t available in the dashboard and requires programmatic use of the Clerk SDK with `handleUserImpersonation`.

Q: What if I try to build a **waitlist** using only the **authentication dashboard**?
A: You won’t find waitlist controls in `Dashboard > Authentication`; waitlists are managed under `Dashboard > Apps > [Your App] > Waitlists` and require the **Build UI-driven custom flows** path.

Q: Can I use **email link verification** without writing code?
A: Partially—you can enable email links in `Dashboard > Authentication` > `Sign-in methods`, but handling the redirect and verification logic still requires the **Clerk SDK** and `handleEmailLinkFlow` in code.

Q: What happens if I need **bot protection** but avoid the API path?
A: Bot protection (via `addBotProtectionToSignUpFlow`) is only available through SDK hooks—you cannot enable it via dashboard alone.

Q: Do I still need the **Clerk SDK** if I use the dashboard-only approach?
A: Yes—all paths require the Clerk SDK installed in your project, even if you write no authentication code.

Q: Can I combine paths?
A: Yes—for example, configure Google login via dashboard, then use `useSignIn` to customize the post-login redirect. But core flow logic must align with one primary path.

### [Manage access](https://company-skill.com/p/clerk/clerk-manage-access.md)

## What You Want to Do

You want to control who can access what in your application—whether by user role, organization membership, or custom permission—and decide how that logic is enforced (in code, via dashboard, or through user-facing UI).

**Typical User Questions**:
- How to implement role-based access control with Clerk?
- How to protect content based on user roles?

## Decision Tree

Pick the best path for your situation:

- **If** you need runtime access checks in code (e.g., using `useAuth()` in a Next.js component or verifying tokens in an API route with `CLERK_SECRET_KEY`) → Use **Use authorization APIs and Protect component** (go to *clerk/clerk-authz*)
- **If** you're defining roles/permissions once in the Clerk dashboard using **JWT Templates**, **shortcodes**, **Client ID**, and **Client Secret** for OAuth providers like Google or GitHub → Use **Configure roles and permissions via guides** (go to *clerk/clerk-auth-authz*)
- **If** end users need to manage their own organization permissions via UI using components like `OrganizationProfile.Page`, `OrganizationProfile.Link`, or features like **Invite Users** and **Waitlists** → Use **Customize profile UI for access management** (go to *clerk/clerk-user_mgmt*)
- **Otherwise (default)** → Start with **Configure roles and permissions via guides** if you’re setting up basic RBAC without code; otherwise, use **Use authorization APIs and Protect component** for dynamic enforcement.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use authorization APIs and Protect component | Enforcing access rules programmatically in frontend/backend code. | medium | Yes | Yes | Supports `useReverification()` for step-up auth and `OAuth token verification` in backend | `clerk/api/clerk-authz` |
| Configure roles and permissions via guides | Setting up RBAC and custom permissions through documented patterns and dashboard settings. | low | No | No | Uses **JWT Templates** with **shortcodes** and configures **Social Connections** via **Client ID**/**Client Secret** | `clerk/guide/clerk-auth-authz` |
| Customize profile UI for access management | Extending user/org profile interfaces to expose permission controls to end users. | medium | Yes | No | Adds **Custom Navigation Items** via `OrganizationProfile.Link` with `label` and `url` | `clerk/guide/clerk-user_mgmt` |

## Path Details

### Path 1: Use authorization APIs and Protect component

**Best For**: Enforcing access rules programmatically in frontend/backend code.

**Brief Description**: This path uses Clerk’s SDK hooks like `useAuth()` and the `<Protect>` component to conditionally render UI based on user **role** or **permission**. It also enables server-side **OAuth token verification** using the `auth()` helper and `CLERK_SECRET_KEY`, and supports advanced flows like step-up authentication via `useReverification()`. Custom metadata like `publicMetadata` can be used to store and evaluate access rules.

**Key technical facts**:
- Billing: Included in standard pricing tiers; free up to 10,000 monthly active users (MAUs)
- Runtimes: Next.js, React, React Router, Android
- Prerequisites: Clerk SDK package (@clerk/nextjs, @clerk/clerk-react, etc.), Node.js version 18.x or higher, `CLERK_SECRET_KEY` environment variable, `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` for frontend

**When to Use**:
- Need programmatic enforcement of access rules in frontend/backend code
- Implementing role-based access control (RBAC) with custom metadata
- Protecting UI components conditionally based on roles/permissions using `<Protect>`
- Verifying OAuth tokens issued by Clerk in backend services
- Implementing step-up authentication flows with `useReverification()` hook

**When NOT to Use**:
- Prefer configuring access control through dashboard without writing code
- Need to customize profile UI interfaces for end-user permission management
- Looking for low-code/no-code setup of RBAC and permissions

**Known Limitations**:
- Maximum of 50 custom roles per organization
- Maximum of 100 custom permissions per organization
- Rate limit of 100 requests per second per API key

### Path 2: Configure roles and permissions via guides

**Best For**: Setting up RBAC and custom permissions through documented patterns and dashboard settings.

**Brief Description**: This no-code path configures authorization through the Clerk dashboard. You define **JWT Templates** using **shortcodes** to inject custom claims (e.g., roles), set up **Social Connections** by entering identity provider **Client ID** and **Client Secret**, and customize the **Authentication menu** with **Custom Pages** and **Custom Navigation Items**. The **AuthView** component (for Android/iOS) reflects these settings.

**Key technical facts**:
- Billing: Free up to 10,000 monthly active users
- Runtimes: Android, iOS
- Prerequisites: Clerk account set up, Application already created in dashboard, SDK installed in project (for AuthView configuration)

**When to Use**:
- Setting up RBAC through dashboard without writing code
- Configuring JWT templates with custom claims using dynamic shortcodes
- Customizing authentication UI appearance through dashboard settings
- Setting up OAuth/OIDC identity providers through guided configuration
- Adding custom navigation items to user/organization profiles via console

**When NOT to Use**:
- Need programmatic control over authorization logic in application code
- Require conditional access based on complex business logic
- Implementing step-up authentication flows requiring custom reverification UI
- Need to verify tokens programmatically in backend services

**Known Limitations**:
- Cannot specify redirect URL or metadata when creating invitations via UI
- OAuth configurations require valid credentials from identity provider to work
- JWT template modifications require understanding of JSON structure and Clerk shortcodes
- AuthView configuration limited to Android and iOS SDKs only

### Path 3: Customize profile UI for access management

**Best For**: Extending user/org profile interfaces to expose permission controls to end users.

**Brief Description**: This path enhances the user and organization profile experience by adding custom UI elements. Using `OrganizationProfile.Page` and `OrganizationProfile.Link`, you can insert **Custom Navigation Items** with a `label` and `url` that point to internal or external resources. Features like **Invite Users**, **Waitlists**, and **Profile Settings** allow end users to manage memberships and access directly. Requires framework-specific setup across **Next.js**, **React**, **Vue**, **Astro**, and others.

**Key technical facts**:
- Billing: Free tier includes up to 10,000 monthly active users and 10,000 waitlist entries per month
- Runtimes: Astro, Vue, Next.js, React, Expo, TanStack React, Start React Router, Chrome Extension, Nuxt
- Prerequisites: Clerk SDK installed in project, User authentication configured, Framework-specific setup, Organizations feature enabled

**When to Use**:
- Extending user/org profile interfaces with custom permission controls visible to end users
- Adding external links or internal pages to profile navigation menus
- Setting up waitlists for user sign-ups with framework-specific implementation
- Configuring organization slugs in URLs for better multi-tenant routing
- Managing organization memberships and roles through admin interface

**When NOT to Use**:
- Need server-side token verification for API endpoints
- Implementing conditional rendering based on roles/permissions in code
- Setting up basic RBAC without custom UI extensions
- Prefer programmatic user management over dashboard operations

**Known Limitations**:
- First item in organization profile navigation cannot be a custom link
- Bulk user deletion not supported via dashboard
- Waitlist name must be unique within the app
- Custom pages require matching route paths in application routing
- Organization slugs must be explicitly enabled before use in URLs

## FAQ

Q: Which path should I start with?
A: If you’re building a new app and need dynamic access control (e.g., hiding buttons based on role), start with **Use authorization APIs and Protect component**. If you just need static roles assigned at login, begin with **Configure roles and permissions via guides**.

Q: What if I need to verify tokens in my backend API but chose the dashboard-only path?
A: You’ll hit a dead end—you won’t have access to `CLERK_SECRET_KEY`-based **OAuth token verification** or the `auth()` helper, forcing you to switch to the API path later.

Q: What if I try to add a custom permission UI for org members but use the dashboard-only path?
A: You can’t—**Custom Navigation Items** and `OrganizationProfile.Page` require code integration. The dashboard path only configures auth flows, not user-facing permission UIs.

Q: Can I combine multiple paths?
A: Yes—most apps use **Configure roles and permissions via guides** to define roles in the dashboard, then **Use authorization APIs and Protect component** to enforce them in code, and optionally **Customize profile UI** to let admins manage members.

Q: What happens if I exceed 50 custom roles per organization using the API path?
A: You’ll hit a hard limit—Clerk enforces a maximum of 50 custom roles and 100 custom permissions per organization, as stated in the limitations.

Q: Why can’t I use AuthView on web frameworks like Next.js?
A: **AuthView** is only supported on **Android** and **iOS** SDKs—the dashboard path’s mobile-specific features don’t apply to web runtimes.

Q: Do I need `publicMetadata` to implement RBAC?
A: Not necessarily—basic roles can come from **JWT Templates** via **shortcodes**, but `publicMetadata` is required if you need to store and evaluate custom role data programmatically in your app.


## Frequently asked questions

### How do I customize the appearance of Clerk UI components?

You can customize the appearance of Clerk UI components by applying themes, CSS variables, or custom styles. This customization is supported through appearance props, programmatic APIs, and console-based configuration guides.

### How do I handle authentication errors and exceptions?

You can handle authentication errors by debugging sign-in and sign-up exceptions, webhook delivery issues, and other integration problems. Clerk provides dedicated troubleshooting resources and best practice guides to help you resolve these issues.

### How do I implement a custom authentication flow?

You can implement a custom authentication flow by building tailored sign-in and sign-up experiences like email link or Google One Tap. These custom paths allow you to design authentication experiences that match your specific application requirements.

### How do I manage user and organization access control?

You can manage user and organization access control by implementing role-based access control to protect content based on assigned user roles. This involves configuring permissions and authorization logic through Clerk's APIs or management dashboard.

## Cross-product integrations

- [Auth email delivery troubleshooting](https://company-skill.com/p/_combos/auth-email-delivery-troubleshooting-976ab1.md) (resend)
- [Branded SaaS Auth-to-Payment Onboarding Flow](https://company-skill.com/p/_combos/branded-saas-auth-to-payment-onboarding-flow-048510.md) (stripe)
- [Branded SaaS Onboarding with Custom Stripe Elements](https://company-skill.com/p/_combos/branded-saas-onboarding-with-custom-stripe-eleme-eab729.md) (stripe + ecs + oss + terraform + es)
- [CI/CD Terraform Full-Stack with Security Hardening](https://company-skill.com/p/_combos/ci-cd-terraform-full-stack-with-security-hardeni-a12154.md) (ecs + terraform + alinux + oss + rds)
- [Complete Domain Email Infrastructure Setup](https://company-skill.com/p/_combos/complete-domain-email-infrastructure-setup-d5499a.md) (resend + alimail + rds)
- [Compliant Infra with ML Search and SCIM Onboarding](https://company-skill.com/p/_combos/compliant-infra-with-ml-search-and-scim-onboardi-968659.md) (alinux + oss + rds + ecs + terraform)
- [Employee Onboarding with Auto-Scaling Infrastructure](https://company-skill.com/p/_combos/employee-onboarding-with-auto-scaling-infrastruc-35b76b.md) (eb + rds + alinux + oss + ecs)
- [End-to-End Ingest-React-Scale Data Platform](https://company-skill.com/p/_combos/end-to-end-ingest-react-scale-data-platform-c04b01.md) (alinux + ecs + eb + supabase + ess)

## Use with an AI agent

```bash
curl -s https://company-skill.com/api/route \
  -H 'Content-Type: application/json' \
  -d '{"query": "...", "product": "clerk"}'
```

MCP server: https://company-skill.com/api/mcp/clerk.py

---
Machine-readable: https://company-skill.com/llms.txt · https://company-skill.com/sitemap.xml