# How the Copilot SDK Prioritizes Authentication Credentials: 5-Level Priority Chain Explained

> Discover the 5-level priority chain the GitHub Copilot SDK uses for authentication credentials. Learn how it prioritizes tokens, env vars, and CLI for seamless access.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: deep-dive
- Published: 2026-07-18

---

**The GitHub Copilot SDK follows a strict five-level priority chain when selecting authentication credentials, starting with explicit programmatic tokens and falling back through environment variables, stored OAuth credentials, and finally GitHub CLI authentication.**

The `github/copilot-sdk` repository implements consistent credential resolution logic across all supported languages. Understanding this **authentication credentials priority** chain helps developers configure secure, predictable access to GitHub Copilot services in both interactive and CI/CD environments.

## The Five-Level Authentication Priority Chain

According to the authentication guide in [`docs/auth/authenticate.md`](https://github.com/github/copilot-sdk/blob/main/docs/auth/authenticate.md) (lines 100-108), the SDK evaluates potential credentials in the following strict order:

### 1. Explicit Programmatic Tokens

The SDK always prefers a token supplied directly via code. When initializing any client, passing the `gitHubToken` option in the constructor overrides all other sources.

This approach ensures developers maintain explicit control over authentication in production environments, preventing accidental credential leakage from system environments or user sessions.

### 2. Direct API Token Environment Variables

If no explicit token is provided, the SDK checks for a raw Copilot API token via the `GITHUB_COPILOT_API_TOKEN` environment variable, which must be paired with `COPILOT_API_URL` to define the endpoint.

This configuration supports advanced use cases requiring direct API access without standard GitHub token flows.

### 3. Standard GitHub Token Environment Variables

The SDK searches three specific environment variables in sequence, using the first valid token encountered:
- `COPILOT_GITHUB_TOKEN`
- `GH_TOKEN`
- `GITHUB_TOKEN`

This tier accommodates common developer workflows where standard GitHub personal access tokens are already configured for other tooling.

### 4. Stored OAuth Credentials

When a user previously authenticated via the `copilot` CLI login command, the SDK retrieves stored credentials from the system keychain.

These credentials persist across sessions, enabling seamless interactive development without repeated authentication prompts.

### 5. GitHub CLI Authentication

As the final fallback, the SDK queries authentication information managed by the GitHub CLI (`gh auth status`).

This ensures compatibility with existing developer setups where `gh` serves as the primary GitHub authentication mechanism.

## Implementation Across Language SDKs

Each language implementation enforces this priority chain through dedicated client initialization modules:

- **Node.js / TypeScript**: [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts) reads `process.env.COPILOT_GITHUB_TOKEN`, `process.env.GH_TOKEN`, and `process.env.GITHUB_TOKEN` before checking the keychain or `gh` CLI.
- **Python**: [`python/copilot/client.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot/client.py) performs identical environment-variable validation and uses the `keyring` library for secure credential storage access.
- **Go**: [`go/client.go`](https://github.com/github/copilot-sdk/blob/main/go/client.go) implements the priority logic using `os.Getenv` and the `github.com/zalando/go-keyring` package.
- **.NET**: [`dotnet/CopilotClient.cs`](https://github.com/github/copilot-sdk/blob/main/dotnet/CopilotClient.cs) follows the same pattern using `Environment.GetEnvironmentVariable` for cross-platform compatibility.
- **Java**: [`java/src/main/java/com/github/copilot/CopilotClient.java`](https://github.com/github/copilot-sdk/blob/main/java/src/main/java/com/github/copilot/CopilotClient.java) checks the three environment variables before consulting CLI configuration files.

## Practical Code Examples

### Node.js: Explicit Token Configuration

Use the `gitHubToken` option to force the highest priority credential and disable fallback mechanisms:

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  gitHubToken: "ghu_XXXXXXXXXXXXXXXXXXXXXXXX",
  useLoggedInUser: false,
});

```

### Python: Environment Variable Fallback

When relying on environment variables, the client automatically discovers the first available valid token:

```python
import os
from copilot import CopilotClient

# Requires: export COPILOT_GITHUB_TOKEN=ghu_XXXXXXXXXXXXXXXXXXXXXXXX

client = CopilotClient()
await client.start()

```

### Go: Disabling Automatic Login

Prevent the SDK from falling back to stored or CLI credentials:

```go
import copilot "github.com/github/copilot-sdk/go"

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        GitHubToken:     "",
        UseLoggedInUser: copilot.Bool(false),
    })
}

```

### .NET: Forcing Explicit Authentication

Programmatically control credential selection in C# applications:

```csharp
using GitHub.Copilot;

var client = new CopilotClient(new CopilotClientOptions {
    GitHubToken = "ghu_XXXXXXXXXXXXXXXXXXXXXXXX",
    UseLoggedInUser = false
});
await using var _ = client;

```

### Java: Environment Variable Integration

Explicitly bind environment variables while maintaining priority logic:

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.CopilotClientOptions;

var client = new CopilotClient(new CopilotClientOptions()
    .setGitHubToken(System.getenv("COPILOT_GITHUB_TOKEN"))
    .setUseLoggedInUser(false));
client.start().get();

```

## Why This Order Matters

The **Copilot SDK authentication credentials priority** chain balances security with developer experience. By checking explicit tokens first, the SDK prevents accidental credential leakage from shared environments or stored sessions. The structured fallback ensures that CI/CD pipelines, interactive development, and CLI-based workflows all function without redundant configuration.

This design allows teams to enforce strict authentication in production (via explicit tokens) while maintaining convenience for local development (via CLI or stored credentials).

## Summary

- The SDK evaluates credentials in a strict five-level hierarchy: explicit tokens → direct API tokens → environment variables (`COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN`) → stored OAuth → GitHub CLI.
- Implementation is consistent across Node.js ([`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts)), Python ([`python/copilot/client.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot/client.py)), Go ([`go/client.go`](https://github.com/github/copilot-sdk/blob/main/go/client.go)), .NET ([`dotnet/CopilotClient.cs`](https://github.com/github/copilot-sdk/blob/main/dotnet/CopilotClient.cs)), and Java ([`java/src/main/java/com/github/copilot/CopilotClient.java`](https://github.com/github/copilot-sdk/blob/main/java/src/main/java/com/github/copilot/CopilotClient.java)).
- Use the `useLoggedInUser: false` option (or language equivalent) to disable fallback to stored or CLI credentials.
- The priority chain is documented in [`docs/auth/authenticate.md`](https://github.com/github/copilot-sdk/blob/main/docs/auth/authenticate.md) lines 100-108.

## Frequently Asked Questions

### How do I override all other credentials in the Copilot SDK?

Pass the `gitHubToken` parameter directly when constructing the client. This explicit approach takes precedence over environment variables, stored credentials, and CLI authentication in all supported languages.

### What happens if multiple environment variables are set?

The SDK checks `COPILOT_GITHUB_TOKEN` first, then `GH_TOKEN`, then `GITHUB_TOKEN`, using the first valid token it encounters. It does not merge or combine tokens from multiple sources.

### Can I disable fallback to CLI and stored credentials?

Yes. Set the `useLoggedInUser` option (or `UseLoggedInUser` in .NET/Java, `UseLoggedInUser` in Go) to `false` during client initialization. This restricts authentication to only explicit tokens and environment variables.

### Why does the SDK check GitHub CLI credentials last?

The GitHub CLI (`gh`) serves as a universal fallback because it represents the broadest authentication context. Checking it last ensures that application-specific configurations (explicit tokens, environment variables) take precedence over user-level CLI settings, preventing unintended authentication contexts in multi-tenant or shared development environments.