# Manage access

Part of **Clerk**. Route queries via `POST https://www.company-skill.com/api/route`.

## 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.

## Related queries

manage user access, manage org access, role-based access control, RBAC, protect content by role, customize organization permissions, add custom profile items, how to implement RBAC with Clerk, how to protect pages by role, how to set org permissions, how to let users manage roles, Clerk access contr

---
Part of [Clerk](https://www.company-skill.com/p/clerk.md) · https://www.company-skill.com/llms.txt