OpenWikishadcn-ui/ui

Registry Authentication

Registry authentication is the part of the shadcn registry workflow that lets an organization keep some registry items private, personalized, licensed, or limited to a specific audience. A registry is a JSON-distribution surface consumed by the shadcn CLI; authentication adds request-level rules around who may retrieve a registry item. The first-party documentation frames this as a way to run private registries, protect business logic, assign different resources to different teams or users, and collect usage signals about who installs what. That makes authentication most relevant once a registry stops being a public catalog and becomes part of an internal platform, design system, commercial product, or controlled rollout process.

Sources: apps/v4/content/docs/registry/authentication.mdx

Purpose and Scope

Use this page when you already understand the basic registry model and need to decide how private or protected registry sources should be configured. The shadcn docs support several deployment styles: a registry can be a custom HTTP service, a framework route that serves JSON, or a public GitHub repository with a root registry manifest. Authentication belongs to the custom or namespaced HTTP registry path, not the public GitHub shortcut. The GitHub registry guide explicitly says GitHub addresses are for public repositories and that private repositories or GitHub Enterprise hosts are not currently supported by GitHub addresses. For those cases, the recommended direction is a namespace paired with authentication.

Sources: apps/v4/content/docs/registry/github.mdx, apps/v4/content/docs/registry/authentication.mdx

The important boundary is that authentication protects the registry request; it does not change the registry schema itself. The registry still returns valid registry and registry-item JSON, and the CLI still installs files described by those objects. The February schema changelog explains the broader registry goal as defining code as flat JSON and distributing it through the CLI, including custom styles, components, tokens, hooks, animations, Tailwind layers, and utilities. Later changelogs expand that distribution model beyond React components, but protected access remains a layer around retrieval rather than a different item format.

Sources: apps/v4/content/docs/changelog/2025-02-registry-schema.mdx, apps/v4/content/docs/changelog/2025-07-universal-registry.mdx

Relevant Source Files

  • apps/v4/content/docs/registry/authentication.mdx — Primary guide for authentication use cases, client configuration patterns, server-side authorization examples, and advanced access-control scenarios.
  • apps/v4/content/docs/registry/github.mdx — Explains when public GitHub repositories can act as registries and when private or authenticated registries should use namespaces and authentication instead.
  • apps/v4/content/docs/changelog/2025-02-registry-schema.mdx — Records the schema update that positions registries as flat JSON distribution for components, tokens, hooks, utilities, and Tailwind assets.
  • apps/v4/content/docs/changelog/2025-07-universal-registry.mdx — Documents universal registry items, which widen the protected content surface to code, config, rules, docs, and other project files.
  • apps/v4/content/docs/changelog/2025-09-registry-index.mdx — Documents registry index discovery through the CLI without preconfiguring components.json, which contrasts with private registry configuration.
  • apps/v4/content/docs/changelog/2025-10-registry-directory.mdx — Documents the public Registry Directory and its no-config discovery flow, another contrast point for authenticated private sources.

Authentication Models in components.json

The documented client-side contract is a registry namespace configured in components.json with a URL template and optional request metadata. A namespace such as @private, @company, or @internal points the CLI at a registry endpoint containing a name placeholder. Authentication values are expressed as headers or query parameters, and the docs show environment variable interpolation for secret material. This keeps the registry address reusable while allowing each developer, CI job, or workspace to provide its own token, API key, workspace identifier, or access token through environment-specific settings rather than hard-coding secrets into shared project configuration.

Sources: apps/v4/content/docs/registry/authentication.mdx

Bearer-token authentication is the most direct pattern. The registry entry provides an Authorization header whose value is built from an environment variable, and developers place the secret in an environment file or another secret source. This pattern fits internal registries backed by simple token stores, JWT verification, or identity-provider-issued access tokens. The docs also show API key authentication with custom headers, including both an API key and a workspace identifier. That second header is useful when the registry service needs to distinguish tenants, teams, billing accounts, or product areas before deciding which registry item a request may retrieve.

Sources: apps/v4/content/docs/registry/authentication.mdx

Query-parameter authentication is shown as a simpler setup. Instead of sending a header, components.json defines params that are appended to the registry item URL, producing a request such as a component-specific JSON URL with a token parameter. This can be convenient for lightweight services or temporary internal tools, but it is easier to leak through logs, browser history, proxy traces, or shared links. In a production private registry, prefer header-based authentication unless the server, hosting platform, or legacy gateway requires a query parameter. The shadcn configuration supports both shapes, so choose based on the registry infrastructure and the organization’s secret-handling policy.

Sources: apps/v4/content/docs/registry/authentication.mdx

components.json
{
  "registries": {
    "@private": {
      "url": "https://registry.company.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Server-Side Request Flow

On the server side, the documented Next.js route demonstrates a clear sequence that registry maintainers can adapt. First, the route extracts credentials from the incoming request, either by reading the authorization header and removing the bearer prefix or by looking for a token query parameter. Second, it validates the token and returns an unauthorized response when no acceptable credential is present. Third, it performs item-level authorization, returning forbidden when the token is valid but lacks access to the requested component. Finally, it loads and returns the registry item JSON for the requested name.

Sources: apps/v4/content/docs/registry/authentication.mdx

That distinction between unauthorized and forbidden is important for private registry operations. Unauthorized means the caller has not proven identity or has presented an invalid credential. Forbidden means the caller is recognized but should not receive the requested item. Keeping those outcomes separate helps developers troubleshoot configuration mistakes without weakening access control. For example, a missing environment variable in components.json should lead to an authentication failure, while a valid contractor token requesting an unreleased admin dashboard kit should lead to an authorization failure. The Express example in the docs shows the same basic idea in a smaller server: extract the bearer token, validate it, return an error if invalid, then serve the item if it exists.

Sources: apps/v4/content/docs/registry/authentication.mdx

The advanced pattern is not merely token checking; it is policy evaluation. The authentication guide introduces team-based access as a way to give different teams different components. In practice, that means a registry service should map the credential to a principal, map the principal to teams, roles, licenses, or entitlements, and then decide whether the requested registry item belongs to an allowed set. This is where private components, team-specific resources, access control, usage analytics, and licensing converge. A registry can serve the same item format to everyone while changing the available catalog according to identity and policy.

Sources: apps/v4/content/docs/registry/authentication.mdx

Choosing Between Public Discovery and Protected Registries

The registry ecosystem now includes multiple discovery paths, and authentication should be chosen deliberately. The September registry index changelog says users can search, view, and add items from the registry index without manually configuring components.json; registries are added automatically when items are installed from the index. The October registry directory changelog describes a browsable directory built into the CLI with no configuration required. Those features are ideal for open-source registries intended for broad discovery. They are not substitutes for private access because their value is public discoverability and easy installation, not per-user policy checks.

Sources: apps/v4/content/docs/changelog/2025-09-registry-index.mdx, apps/v4/content/docs/changelog/2025-10-registry-directory.mdx

Use a public GitHub registry when the source repository is public, the root registry file is valid, referenced files exist, and consumers can install directly from an owner, repository, and item address. The GitHub guide emphasizes that this model needs no registry server and no generated JSON publishing step because the repository itself becomes the source registry. It is excellent for reusable open-source utilities, project conventions, docs, templates, workflows, rules, and MCP configuration. Move to a namespaced authenticated registry when the content should not be public, when request authentication is required, or when different users should receive different catalogs or items.

Sources: apps/v4/content/docs/registry/github.mdx

Universal registry items increase the importance of this decision. The July changelog says registry items can now be distributed to any project with no framework, components.json, Tailwind, or React requirement, unlocking distribution of code, config, rules, docs, and anything else. That means a protected registry might distribute sensitive onboarding rules, internal CI workflows, feature kits, migration scripts, or paid design assets, not only UI components. Authentication should therefore be reviewed as part of the registry’s overall information architecture: determine what is public, what is discoverable but gated, what is internal-only, and what requires role-based or license-based entitlement checks.

Sources: apps/v4/content/docs/changelog/2025-07-universal-registry.mdx

Implementation Checklist

Start by deciding the addressing model. If consumers will install public items from an open GitHub repository, follow the GitHub registry model. If the registry needs private access, define a namespace in components.json that points to the protected registry endpoint. Next, choose a credential transport. Bearer tokens are the documented default-style option; custom API key headers work well for gateways and multi-tenant platforms; query parameters are available for simpler setups but should be evaluated carefully. Then define the server policy: validate credentials, authorize access to the requested item, return clear error status codes, and only then return valid registry item JSON.

Sources: apps/v4/content/docs/registry/authentication.mdx, apps/v4/content/docs/registry/github.mdx

For teams operating the registry, the final step is to make authentication observable without exposing secrets. The authentication guide lists usage analytics as a use case, so log the principal, workspace, registry namespace, item name, decision, and timestamp rather than the raw token. Keep token values in environment variables or secret managers, rotate them when team membership changes, and test both success and failure paths before publishing a registry endpoint to developers. When troubleshooting, ask whether the CLI is resolving the intended namespace, whether the environment variables are present, whether the server sees the expected header or query parameter, and whether the authorization rule allows that specific item.

Sources: apps/v4/content/docs/registry/authentication.mdx

Read Registry Overview before this page if you need the broader distribution model for custom components, hooks, pages, config, rules, and other files. Read Registry Namespaces next when you need to understand how an address such as a scoped registry item maps to a configured source. Read Registry Schema when building the JSON payloads that authenticated endpoints return, and read Registry Index or Registry Directory when deciding whether a registry should be public and discoverable instead of private. For a practical rollout, create a small private namespace, serve one low-risk registry item, validate authentication in a local environment, and then expand the policy to teams, licenses, and production secrets.

Ask a question...