Skip to main content
Copilot API handles two distinct kinds of authentication: your GitHub identity (how the proxy authenticates to GitHub Copilot) and optional client authentication (how your AI tools authenticate to the proxy). This page covers both.

​
Authenticate with GitHub

​
Default device flow

Run the auth command to start a GitHub OAuth device flow: 
npx @nick3/copilot-api@latest auth
The command prints a short code and a URL. Open github.com/login/device in your browser, enter the code, and approve the login. Once approved, the proxy saves your GitHub token locally under ~/.local/share/copilot-api/ (Linux/macOS) or %USERPROFILE%\.local\share\copilot-api\ (Windows). You only need to authenticate once. The proxy refreshes the Copilot token automatically at runtime.

​
OpenCode OAuth app

If you use OpenCode, authenticate with the OpenCode OAuth app. This behaves identically to OpenCode’s built-in GitHub Copilot provider and carries no additional Terms of Service implications: 
npx @nick3/copilot-api@latest --oauth-app=opencode auth
You can also set this permanently with an environment variable so you don’t need to pass the flag every time: 
export COPILOT_API_OAUTH_APP=opencode
npx @nick3/copilot-api@latest auth

​
Provide a token directly

If you already have a GitHub token (generated by running auth previously), you can pass it directly to the start command instead of going through the device flow again: 
npx @nick3/copilot-api@latest start --github-token ghp_YOUR_TOKEN_HERE
This creates a temporary account for that run. The token is not saved to the account registry.

​
GitHub Enterprise

To connect to a GitHub Enterprise instance, pass the enterprise hostname: 
npx @nick3/copilot-api@latest --enterprise-url=company.ghe.com start
Or set the environment variable: 
export COPILOT_API_ENTERPRISE_URL=company.ghe.com
npx @nick3/copilot-api@latest start

​
Manage multiple accounts

You can register more than one GitHub account and the proxy will route requests across them automatically. Premium model requests use accounts in order and fall back when quota is exhausted. Free model requests are distributed round-robin by default.

​
Add an account

npx @nick3/copilot-api@latest auth add
Run this command again for each additional account. Each account goes through its own device flow.

​
List accounts

# List all registered accounts
npx @nick3/copilot-api@latest auth ls

# List accounts with quota information (requires an API call)
npx @nick3/copilot-api@latest auth ls -q

​
Remove an account

# Remove by 1-based index (as shown in auth ls)
npx @nick3/copilot-api@latest auth rm 2

# Remove by GitHub username
npx @nick3/copilot-api@latest auth rm octocat
The index used in auth rm is 1-based, matching the list shown by auth ls. The /usage/:accountIndex API endpoint uses a 0-based index.

​
Require API keys from clients

By default the proxy accepts requests from any client. To require authentication, add one or more API keys to config.json: Location: ~/.local/share/copilot-api/config.json (Linux/macOS) or %USERPROFILE%\.local\share\copilot-api\config.json (Windows) 
{
  "auth": {
    "apiKeys": ["your-key-1", "your-key-2"]
  }
}
Restart the proxy after editing config.json. Clients must then send one of the configured keys with every request using either header: 
# Using x-api-key
curl http://localhost:4141/v1/models \
  -H "x-api-key: your-key-1"

# Using Authorization: Bearer
curl http://localhost:4141/v1/models \
  -H "Authorization: Bearer your-key-1"
You can configure multiple keys for rotation — any one of them is accepted.
When no keys are configured, authentication is disabled and the proxy accepts all requests. The auth.apiKeys field takes precedence over the legacy COPILOT_API_KEY environment variable, which is still accepted for backward compatibility.

​
Admin UI access control

The Admin UI (/admin) and Admin API (/api/admin/*) use separate access control from the client API keys above:
  • Loopback access (localhost, 127.0.0.1, ::1) is always allowed without a token.
  • Remote access requires setting the ADMIN_TOKEN environment variable on the server and sending it via x-admin-token: <token> or Authorization: Bearer <token>.
Do not expose the proxy to the public internet without configuring both auth.apiKeys and ADMIN_TOKEN. Without these, any client on the network can make requests and access the Admin UI.