Shareable tenant links
Public-facing organization content
Clerk · Pipe
orgSlug
Clerk organization slugs are readable identifiers, such as acme-corp, that can appear in URL paths. Clerk can use matching slug routes to activate the corresponding organization and support tenant-specific navigation.
How it works
An organization slug is a readable identifier placed in a URL path, such as /orgs/acme-corp. Clerk middleware can recognize the matching route pattern and make the organization represented by the slug active for the session; components can also be configured to navigate to slug-based URLs.
Syntax
organizationPatterns: ['/orgs/:slug', '/orgs/:slug/(.*)']Parameters
| Name | Type | Description |
|---|---|---|
organizationPatterns | string[] | URL route patterns that identify organization-specific paths and contain :slug or :id. |
Key points
- A slug is a readable organization identifier intended for use in URL paths.
- Including the slug in an organization-scoped path makes the tenant explicit in the route.
- Slug URLs are especially useful when users share organization-specific public links.
- Frequent switching among organizations is another documented reason to use slug-based URLs.
- These components provide navigation settings for managing organization slugs and IDs in application URLs.
- A matching slug route, including trailing segments, activates the organization identified by that slug.
Common mistakes
- Use slugs only when URL-level organization context provides a clear benefit; Clerk does not recommend adding them by default.
- The middleware may change the session's active organization when the URL slug identifies a different organization.
Example: Activate an organization from a slug URL
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware({
organizationSyncOptions: {
organizationPatterns: ['/orgs/:slug/(.*)'],
},
})Configure Clerk middleware so a URL containing an organization slug can select that organization as active.
When to use it
Multi-organization navigation
Applications with frequent organization switching
Organization-aware routing
Tenant-scoped application areas
Interview questions
QWhat is an organization slug, and why put it in a URL?
An organization slug is a human-readable URL identifier, for example acme-corp. Putting it in the path makes organization-specific links shareable and gives the current tenant visible URL context.
Follow-up: When should slugs be avoided? Avoid them when most users belong to one organization or when organization-specific URLs do not add meaningful context.
QHow do Clerk components navigate to slug-based organization URLs?
Configure organization navigation properties such as afterCreateOrganizationUrl and afterSelectOrganizationUrl with a route like /orgs/:slug. This makes creation and selection navigate to the slug-based organization path.
Follow-up: Which components support this configuration? Clerk documents OrganizationSwitcher and OrganizationList as components with options for slug- and ID-based navigation.
QHow does middleware activate an organization from a slug path?
Configure middleware organization patterns with a route parameter named :slug, such as /orgs/:slug or /orgs/:slug/(.*). When the request matches, Clerk uses the slug to set that organization as active.
Follow-up: What parameter matches an organization ID instead? Use :id; the documented pattern names are :id for an ID and :slug for a slug.
Related
OrganizationSwitcherOrganizationListafterCreateOrganizationUrlafterSelectOrganizationUrlorganizationSyncOptionsclerkMiddleware