How to Use BYOK (Bring Your Own Key) with the GitHub Copilot SDK

Yes, the GitHub Copilot SDK fully supports BYOK (Bring Your Own Key) configurations, allowing you to integrate custom LLM providers alongside native Copilot models using ProviderConfig and NamedProviderConfig interfaces.

The GitHub Copilot SDK enables developers to extend AI capabilities beyond the default Copilot API (CAPI) by supporting Bring Your Own Key integrations. This architecture allows you to connect proprietary or third-party LLM endpoints while maintaining the SDK's unified interface for model selection and request handling.

Understanding BYOK Architecture in the Copilot SDK

The SDK treats BYOK providers as first-class transport layers. According to the source code in nodejs/src/types.ts, the type system defines two primary configuration interfaces for custom providers.

ProviderConfig and NamedProviderConfig

The ProviderConfig interface (defined at line 2525 in nodejs/src/types.ts) represents a single legacy BYOK provider configuration. For scenarios requiring multiple providers, the NamedProviderConfig interface (line 2636) allows registration of several named BYOK providers within the same session.

These configurations expose critical fields including the transport URL, optional Azure-specific parameters, and the bearerTokenProvider callback. The runtime merges these definitions with built-in CAPI configurations, enabling mixed usage of Copilot-hosted and custom models.

Bearer Token Authentication

Unlike static API keys, the SDK implements dynamic token acquisition through the bearerTokenProvider callback. As implemented in nodejs/src/session.ts (line 876), this callback executes before each outbound request to your BYOK endpoint. The SDK does not cache tokens, ensuring fresh credentials for every request.

The returned token is injected into the Authorization: Bearer <token> header. This design supports short-lived tokens from secret management systems or identity providers.

Configuring BYOK Providers at Session Creation

When initializing a client via the create function, you supply BYOK configurations within the SessionConfig. You may specify either a singular provider or a providers array for multiple named configurations.

Single BYOK Provider

import { create } from '@github/copilot-sdk';

const client = await create({
  session: {
    model: 'gpt-4',
    provider: {
      transport: { url: 'https://my-llm.example.com/v1' },
      bearerTokenProvider: async () => {
        const resp = await fetch('https://my-vault.example.com/token');
        const { access_token } = await resp.json();
        return access_token;
      },
    },
  },
});

Multiple Named Providers

const client = await create({
  session: {
    providers: [
      {
        name: 'my-llm',
        transport: { url: 'https://my-llm.example.com/v1' },
        bearerTokenProvider: async () => 'token-a',
      },
      {
        name: 'enterprise-llm',
        transport: { url: 'https://enterprise.example.com/v1' },
        azure: { deploymentId: 'my-deployment' },
        bearerTokenProvider: async () => 'token-b',
      },
    ],
  },
});

Runtime Model Discovery and Switching

BYOK models integrate seamlessly with the SDK's model selection RPCs. According to nodejs/src/generated/rpc.ts (line 7963), BYOK models appear with provider-qualified selection IDs in the format providerName/modelId.

List all available models (both CAPI and BYOK):

const models = await client.session.model.list();
console.log(models);
// Output includes: "gpt-4", "my-llm/claude-2.1", "enterprise-llm/gpt-4-turbo"

Switch to a BYOK model and generate completions:

await client.session.model.switchTo('my-llm/claude-2.1');

const response = await client.session.copilotRequest({
  prompt: 'Write a short poem about sunrise.',
});
console.log(response.completion);

Dynamic Provider Registration

The SDK supports adding BYOK providers after session initialization via the addProvidersAndModels RPC (defined in nodejs/src/generated/rpc.ts around line 8005). This method accepts new provider configurations and model definitions without requiring session restart.

await client.session.addProvidersAndModels({
  providers: [
    {
      name: 'other-llm',
      transport: { url: 'https://other.example.com/v1' },
      bearerTokenProvider: async () => 'another-token',
    },
  ],
  models: [
    {
      name: 'other-llm/llama-3',
      provider: 'other-llm',
    },
  ],
});

Summary

• The GitHub Copilot SDK supports BYOK through ProviderConfig and NamedProviderConfig interfaces defined in nodejs/src/types.ts.
• Authentication uses a per-request bearerTokenProvider callback (registered in nodejs/src/session.ts) that returns fresh tokens for the Authorization header.
• BYOK models use qualified IDs (providerName/modelId) and are discoverable via standard model.list and model.switchTo RPCs.
• Runtime registration of new providers is possible through the addProvidersAndModels method without session recreation.
• Reference implementations are available in nodejs/test/e2e/provider_endpoint.e2e.test.ts and nodejs/test/e2e/byok_bearer_token_provider.e2e.test.ts.

Frequently Asked Questions

Does the GitHub Copilot SDK cache bearer tokens for BYOK providers?

No. The SDK explicitly does not cache bearer tokens. The bearerTokenProvider callback executes before every request to your custom endpoint, ensuring fresh authentication credentials. This implementation in nodejs/src/session.ts supports rotating or short-lived tokens from vault services.

Can I use both Copilot API models and BYOK models in the same session?

Yes. The runtime merges BYOK configurations with built-in CAPI settings during session creation. You can switch between native models (like GPT-4) and custom BYOK models using model.switchTo() with the appropriate model ID.

What authentication methods are supported for BYOK endpoints?

The SDK primarily supports bearer token authentication via the bearerTokenProvider callback. You return a string token from this async function, which the SDK places in the Authorization: Bearer <token> header. Azure-specific configurations are also supported through optional fields in the provider config.

How do I reference a BYOK model when multiple providers are configured?

Use the provider-qualified format providerName/modelId (for example, "my-llm/claude-2.1"). This naming convention, documented in the RPC definitions at nodejs/src/generated/rpc.ts, allows the runtime to route requests to the correct endpoint.

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