# How to Handle Private Repositories with Context7: A Complete Guide

> Learn how to handle private repositories with Context7. Securely connect to GitHub, GitLab, or Bitbucket by obtaining an API key and authenticating SDK requests. Access private docs easily.

- Repository: [Upstash/context7](https://github.com/upstash/context7)
- Tags: how-to-guide
- Published: 2026-02-16

---

**You can handle private repositories with Context7 by obtaining a Context7 API key (prefixed with `ctx7sk`), registering your repository through the Context7 dashboard, and authenticating all SDK requests with your API key to retrieve up-to-date documentation from private GitHub, GitLab, or Bitbucket repositories.**

Context7 bridges the gap between AI coding assistants and your internal codebase by enabling you to handle private repositories with Context7's documentation indexing service. Whether you're working with proprietary GitHub organizations or self-hosted GitLab instances, Context7 securely surfaces your private documentation to LLMs while maintaining strict access controls through API key authentication and role-based permissions.

## Prerequisites for Handling Private Repositories with Context7

Before you can index internal codebases, you must satisfy two authentication requirements enforced by the Context7 platform.

### API Key Authentication

All requests to private repositories require a **Context7 API key** prefixed with `ctx7sk`. The SDK validates this key during client construction in [`packages/sdk/src/client.ts`](https://github.com/upstash/context7/blob/main/packages/sdk/src/client.ts) (lines 22-27). You can supply the key via the `CONTEXT7_API_KEY` environment variable or pass it directly in the SDK configuration.

### Subscription and Role Requirements

According to the documentation in `docs/howto/private-repositories.mdx`, handling private repositories requires a **Pro or Enterprise** plan. Additionally, you must have **Owner or Admin** role access to the repository you want to index. The Context7 dashboard enforces these checks during the repository registration workflow.

## Step-by-Step Guide to Handling Private Repositories with Context7

Follow this workflow to securely expose your private documentation to AI assistants.

### Step 1: Configure Your Context7 API Key

Set up authentication using either environment variables or direct configuration:

```bash

# .env file (recommended - never commit this to version control)

CONTEXT7_API_KEY=ctx7sk_YourPrivateKeyHere

```

Or configure programmatically in TypeScript:

```typescript
import { Context7 } from "@upstash/context7-sdk";

// Pass the key directly (overrides environment variable)
const client = new Context7({ apiKey: "ctx7sk_YourPrivateKeyHere" });

```

The SDK constructor in [`packages/sdk/src/client.ts`](https://github.com/upstash/context7/blob/main/packages/sdk/src/client.ts) validates that the API key exists and throws a `Context7Error` if authentication credentials are missing.

### Step 2: Register Your Private Repository via the Dashboard

Navigate to the Context7 dashboard to authorize repository access:

1. Open https://context7.com/add-library
2. Connect your GitHub, GitLab, or Bitbucket account
3. Authorize the Context7 GitHub App (or equivalent OAuth integration) with repository access permissions
4. Select the private repository you want to index from the dropdown
5. Click **Submit** to trigger the parsing pipeline

As documented in `docs/howto/private-repositories.mdx`, the dashboard displays **Refresh** and **Remove** controls once indexing completes. Only users with Owner or Admin roles can see private repositories in the selection interface.

### Step 3: Query Documentation from Your Private Repository

Once indexed, retrieve documentation using the library ID format `/github/owner/repo` (or equivalent for GitLab/Bitbucket):

```typescript
import { Context7 } from "@upstash/context7-sdk";

// Initialize client (API key read from CONTEXT7_API_KEY environment variable)
const ctx7 = new Context7();

// Retrieve documentation from private repository
const docs = await ctx7.getContext(
  "How do I authenticate API requests?",
  "/github/your-org/your-private-repo",  // Library ID shown in dashboard
  { type: "json" }                       // Options: "json" (default) or "txt"
);

console.log(docs);
// Returns array of formatted documentation snippets from your private codebase

```

The `GetContextCommand` implementation in [`packages/sdk/src/commands/get-context/index.ts`](https://github.com/upstash/context7/blob/main/packages/sdk/src/commands/get-context/index.ts) (lines 44-47) handles the request formatting and response parsing. The backend validates your API key against the private repository's access control list before returning content.

### Step 4: Refresh Your Private Repository Index

When your private codebase changes, update the documentation index:

1. Navigate to the Context7 dashboard
2. Locate your private repository in the library list
3. Click the **Refresh** button

The server re-parses only changed files; cached pages that haven't changed remain available without consuming additional parsing credits. As noted in the documentation, you cannot trigger refreshes programmatically through the SDK—the dashboard UI controls this operation.

## Understanding the Authentication Flow in the Context7 SDK

The Context7 SDK enforces authentication at the client level. When you instantiate the client, the constructor in [`packages/sdk/src/client.ts`](https://github.com/upstash/context7/blob/main/packages/sdk/src/client.ts) performs the following validation:

```typescript
// packages/sdk/src/client.ts – API key validation (lines 22-27)
const apiKey = config.apiKey || process.env.CONTEXT7_API_KEY;
if (!apiKey) {
  throw new Context7Error(
    "API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable."
  );
}

```

This ensures that every subsequent request—including those to private repositories—includes the necessary authentication headers. The API key (prefixed with `ctx7sk`) unlocks both higher rate limits and access to proprietary content indexed from your private repositories.

## Retrieving Documentation from Private Repositories

When querying private content, the SDK uses the same `getContext` method as for public libraries, but the backend performs additional authorization checks. The `GetContextCommand` in [`packages/sdk/src/commands/get-context/index.ts`](https://github.com/upstash/context7/blob/main/packages/sdk/src/commands/get-context/index.ts) structures the request:

```typescript
// packages/sdk/src/commands/get-context/index.ts (lines 44-47)
// Formats the request to include library ID and query parameters
const response = await this.client.request({
  path: `/libraries/${libraryId}/context`,
  method: "POST",
  body: { query, options }
});

```

The `libraryId` parameter for private repositories follows the pattern `/github/owner/repo` (or `/gitlab/...`, `/bitbucket/...`). The server verifies that the provided API key has access to the specified private repository before returning the `codeSnippets` and `infoSnippets` arrays.

## Summary

- **Obtain a Context7 API key** (prefixed with `ctx7sk`) and configure it via the `CONTEXT7_API_KEY` environment variable or SDK constructor to authenticate requests to private repositories.
- **Register private repositories** through the Context7 dashboard at `context7.com/add-library`, requiring Pro/Enterprise plans and Owner/Admin role permissions.
- **Query private documentation** using the standard SDK `getContext` method with library IDs in the format `/github/owner/repo`; the backend validates your API key before returning proprietary content.
- **Refresh indexes** via the dashboard UI when your private codebase changes; the server optimizes by re-parsing only modified files.

## Frequently Asked Questions

### Do I need a paid plan to handle private repositories with Context7?

Yes, handling private repositories requires a **Pro or Enterprise** subscription. According to the documentation in `docs/howto/private-repositories.mdx`, the repository registration interface enforces this requirement, and only users with active paid plans can authorize the Context7 GitHub App (or equivalent GitLab/Bitbucket integration) to access private codebases.

### How do I find the library ID for my private repository?

The library ID appears in your Context7 dashboard after you register the repository. It follows the pattern `/github/owner/repo` for GitHub repositories, `/gitlab/owner/repo` for GitLab, or `/bitbucket/owner/repo` for Bitbucket. When calling `getContext()` in the SDK, pass this string as the second argument to target your specific private codebase.

### Can I use the Context7 MCP server with private repositories?

Yes, the Model Context Protocol (MCP) server works with private repositories as long as you provide a valid Context7 API key. Configure the `CONTEXT7_API_KEY` environment variable when starting the MCP server process. The server passes this credential through to the Context7 backend, which validates access permissions before returning documentation from your private repositories.

### How often should I refresh my private repository index?

You should refresh your private repository index whenever you make significant changes to the codebase that affect documentation, such as adding new public APIs, updating README files, or modifying configuration schemas. The Context7 dashboard provides a **Refresh** button that re-parses only changed files, preserving cached content to optimize processing time and credit usage.