GitHub Copilot SDK Authentication Methods: 6 Ways to Authenticate

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 (line 2940), the SDK enumerates authentication behaviors through the AuthInfo.type field. The client implementation in 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.

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 (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 demonstrates this flow:

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.

Summary

• The SDK defines six authentication types in 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}