# GitHub Copilot SDK Authentication Methods: 6 Ways to Authenticate

> Explore six GitHub Copilot SDK authentication methods including user, env, gh-cli, hmac, api key, and token. Learn how to secure your integrations.

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

---

**The GitHub Copilot SDK supports six distinct authentication methods—`user`, `env`, `gh-cli`, `hmac`, `api-key`, and `token`—defined in the `AuthInfo.type` enum, plus an optional per-session OAuth flow for Marketplace integrations.**

The `github/copilot-sdk` repository provides a TypeScript client for integrating GitHub Copilot capabilities into custom applications and extensions. Understanding the available GitHub Copilot SDK authentication methods is essential for securing API requests, whether you are building CI/CD pipelines, IDE plugins, or Bring-Your-Own-Key (BYOK) provider integrations.

## Supported Authentication Methods

According to the source code in [`nodejs/src/types.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts) (line 2940), the SDK enumerates authentication behaviors through the `AuthInfo.type` field. The client implementation in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts) handles the selection logic and attaches the appropriate `Authorization` header to outgoing RPC calls.

### User-Scoped OAuth (Default)

The **`user`** type represents the default authentication flow for standard Copilot usage. It utilizes a GitHub user-scoped OAuth token obtained via GitHub Desktop or website OAuth flows. The SDK caches this token internally and refreshes it automatically when it expires. This method activates automatically when the user is logged in via the GitHub CLI or the VS Code extension.

### Environment Variable Token

The **`env`** type reads credentials from the **`GITHUB_TOKEN`** environment variable, or from a custom variable specified via `process.env`. This method is ideal for CI/CD environments and automated scripts where tokens are injected securely through environment configuration rather than hardcoded values.

### GitHub CLI Integration

The **`gh-cli`** type invokes the **GitHub CLI (gh)** binary to retrieve the active user token via the `gh auth token` command. The SDK then forwards this token in the `Authorization: Bearer …` header. This approach works when the GitHub CLI is installed and the user has previously executed `gh auth login`.

### HMAC Request Signing

The **`hmac`** type generates an HMAC signature for each request using a secret key supplied via the `hmacKey` option. This method is designed for BYOK providers that require request-level cryptographic signing rather than standard bearer token authentication.

### Provider API Keys

The **`api-key`** type sends a static API key provided by third-party providers in an `Authorization: ApiKey …` header. This offers a straightforward integration path for services that utilize simple API-key-based authentication schemes without complex signing requirements.

### Raw Bearer Tokens

The **`token`** type allows developers to pass a raw bearer token directly—such as a GitHub Personal Access Token (PAT)—through the `auth: { type: "token", token: "…" }` configuration. This provides explicit control when the token is already known and managed externally.

## Configuring Authentication in Code

The `createClient` function accepts an `auth` configuration object that determines which credential source the SDK uses. Below are runnable implementations for each supported method.

```typescript
import { createClient } from '@github/copilot-sdk';

// 1. User-scoped OAuth (default - auto-detects gh-cli or cached token)
const clientUser = createClient();

// 2. Environment variable token
const clientEnv = createClient({
  auth: { type: 'env', envVar: 'GITHUB_TOKEN' },
});

// 3. Explicit GitHub CLI token lookup
const clientGhCli = createClient({
  auth: { type: 'gh-cli' },
});

// 4. HMAC (BYOK) signing
const clientHmac = createClient({
  auth: {
    type: 'hmac',
    hmacKey: Buffer.from('your-secret-bytes'),
  },
});

// 5. Provider API key
const clientApiKey = createClient({
  auth: { type: 'api-key', apiKey: 'provider-generated-key' },
});

// 6. Raw bearer token (e.g., Personal Access Token)
const clientToken = createClient({
  auth: { type: 'token', token: 'ghp_XXXXXXXXXXXXXXXXXXXX' },
});

```

## Per-Session OAuth for Marketplace Integrations

Beyond static authentication types, the SDK supports dynamic **per-session OAuth** via the Model Context Protocol (MCP) Marketplace flow. When creating a session, the SDK can trigger an OAuth login that yields a temporary token scoped to that specific interaction.

As implemented in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) (line 11540), RPC request payloads include an optional `authType?: AuthInfoType` field that propagates the selected authentication method to the Copilot service. The E2E test in [`nodejs/test/e2e/per_session_auth.e2e.test.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/test/e2e/per_session_auth.e2e.test.ts) demonstrates this flow:

```typescript
await clientUser.start();
const session = await clientUser.createSession({
  model: 'gpt-4',
});

// Trigger OAuth flow for this specific session
await session.rpc.mcp.oauth.login({
  serverName: 'github',
});

```

This pattern is particularly relevant for BYOK providers requiring temporary credentials scoped to individual chat sessions rather than long-lived client tokens, as verified in [`nodejs/test/e2e/mcp_oauth.e2e.test.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/test/e2e/mcp_oauth.e2e.test.ts).

## Summary

- The SDK defines six authentication types in [`nodejs/src/types.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts): `user`, `env`, `gh-cli`, `hmac`, `api-key`, and `token`.
- **Default OAuth** (`user`) automatically manages token refresh for GitHub CLI and IDE extension users.
- **Environment** (`env`) and **GitHub CLI** (`gh-cli`) methods simplify CI/CD and local development workflows.
- **HMAC** (`hmac`) and **API Key** (`api-key`) methods support third-party BYOK providers with specific security requirements.
- **Raw tokens** (`token`) offer explicit control for advanced use cases with existing credentials.
- Per-session OAuth via MCP enables temporary token acquisition for Marketplace integrations, tested in [`nodejs/test/e2e/mcp_oauth.e2e.test.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/test/e2e/mcp_oauth.e2e.test.ts).

## Frequently Asked Questions

### How do I authenticate GitHub Copilot SDK in CI/CD pipelines?

Use the **`env`** authentication type. Set the `GITHUB_TOKEN` environment variable in your CI/CD configuration, then initialize the client with `createClient({ auth: { type: 'env' } })`. The SDK automatically reads the token from the environment without requiring interactive login flows or GitHub CLI installation.

### What is the difference between `gh-cli` and `user` authentication types?

The **`gh-cli`** type explicitly invokes the GitHub CLI binary to retrieve the current token via `gh auth token`, while the **`user`** type relies on the SDK's internal OAuth cache and refresh logic. Both ultimately use GitHub user-scoped OAuth tokens, but `gh-cli` depends on the external CLI tool being installed and authenticated, whereas `user` uses the SDK's native token management.

### When should I use HMAC authentication instead of API keys?

Use **HMAC** (`hmac`) authentication when your BYOK provider requires request-level cryptographic signatures using a shared secret. Use **API keys** (`api-key`) for providers that accept static keys in the Authorization header. HMAC provides stronger security guarantees through per-request signing, while API keys offer simpler integration for services that do not support signature-based authentication.

### Can I use multiple authentication methods in the same application?

Yes. You can instantiate multiple clients with different `auth` configurations within the same application. Each `createClient` call operates independently, allowing you to mix methods such as `env` for background tasks and `user` for interactive features, or switch between `hmac` and `api-key` for different provider endpoints.