Authentication

The Copilot SDK supports multiple authentication methods. Choose one based on your use case.

Authentication methods

Method	Primary use case	Copilot subscription	Notes
GitHub login (CLI)	Development and manual runs	Required	Uses the login session from the `copilot` CLI
OAuth GitHub App / PAT	Per-user tokens	Required	Set via `github_token`
Environment variables	CI/CD and server runtime	Required	`COPILOT_GITHUB_TOKEN`, etc.
BYOK (Bring Your Own Key)	Your own model provider	Not required	Configure a custom provider
Microsoft Entra ID	Built-in sign-in	Requires an Entra app registration	Identify the host app with `entra.clientId`

For BYOK, see custom-providers.md.

Microsoft Entra ID

To use the built-in Microsoft Entra sign-in and token refresh, register your host application with the client. Set clientId to the Application (client) ID of your Entra app registration. You can pass an EntraAuthConfig instance or an array. Empty and whitespace-only values throw an InvalidArgumentException.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\EntraAuthConfig;

Copilot::useStdio([
    'entra' => new EntraAuthConfig(clientId: config('services.entra.client_id')),
])->run(prompt: 'Hello');
Copilot::stop();

You can also pass an array:

Copilot::useStdio([
    'entra' => ['clientId' => config('services.entra.client_id')],
])->run(prompt: 'Hello');
Copilot::stop();

The SDK sends the client ID to the runtime during the server.connect handshake. This registration is separate from the accounts.acquireEntraToken server RPC, which requests a token explicitly. If you set an Entra configuration and the runtime is too old to support connect, the SDK throws This runtime does not support Entra client configuration. instead of silently dropping the setting. Update the runtime in that case. Other authentication methods continue to work.

Network callbacks

Use the network option to delegate the runtime’s proxy resolution and Kerberos Negotiate authentication to callbacks on the host. The Copilot runtime must support the network.setProvider RPC. If it does not, the client throws an exception at startup that asks you to update the runtime. Each callback receives the request type and a CancellationToken you can check for cancellation.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\CancellationToken;
use Revolution\Copilot\Types\Rpc\NetworkAuthenticateNegotiateRequest;
use Revolution\Copilot\Types\Rpc\NetworkResolveProxyRequest;

Copilot::useStdio([
    'network' => [
        'scope' => 'runtime',
        'resolveProxy' => function (NetworkResolveProxyRequest $request, CancellationToken $signal) use ($proxyResolver): ?string {
            return $proxyResolver->resolve($request->url, $signal);
        },
        'authenticateNegotiate' => function (NetworkAuthenticateNegotiateRequest $request, CancellationToken $signal) use ($credentials): ?string {
            return $credentials->acquire($request->spn, $signal);
        },
    ],
])->run(prompt: 'Hello');
Copilot::stop();

resolveProxy returns a PAC-style string such as PROXY proxy.example:8080; DIRECT, or DIRECT for a direct connection. Return null to let the runtime resolve the proxy itself. authenticateNegotiate returns a single-use base64 SPNEGO token without the Negotiate prefix, or null when no credentials are available. If a callback throws, the RPC fails and the runtime does not fall back to a direct connection. Validate the SPN before you issue credentials. scope defaults to connection, which covers only requests from sessions this client created or resumed. runtime also covers shared background traffic, but only one connection at a time can hold this scope. If you are already logged in with copilot or gh CLI, the SDK uses stored credentials by default.

use Revolution\Copilot\Facades\Copilot;

$response = Copilot::run(prompt: 'Hello');

OAuth GitHub App / PAT

Pass a user access token from OAuth, or a fine-grained PAT, to github_token.

Expected token prefixes: gho_, ghu_, github_pat_
ghp_ (classic PAT) is discouraged

use Revolution\Copilot\Facades\Copilot;

$config = array_merge(config('copilot'), [
    'github_token' => $user->github_token,
]);

$response = Copilot::useStdio($config)->run(prompt: '...');
Copilot::stop();

When you set github_token, use_logged_in_user is automatically set to false. To override explicitly:

$config = [
    'github_token' => $user->github_token,
    'use_logged_in_user' => true,
];

For details, see github-token.md. Both github_token and use_logged_in_user are only available in stdio mode. In TCP mode, the Copilot CLI must already be authenticated.

Mask host-generated secrets

If your host application obtains tokens dynamically, such as through MCP OAuth, register them with the Copilot CLI redaction filter. The CLI masks registered values in session logs and exports.

use Revolution\Copilot\Facades\Copilot;

$accessToken = $oauthProvider->getAccessToken();

Copilot::client()->rpc()->secrets()->addFilterValues([
    'values' => [$accessToken],
]);

This call is separate from obtaining and passing tokens with onMcpAuthRequest. Call it explicitly after you obtain a token. The SDK does not persist the values or log them separately for this RPC.

Environment variables

If you pass a token via environment variables, the CLI auto-detects it using this priority order:

COPILOT_GITHUB_TOKEN
GH_TOKEN
GITHUB_TOKEN

COPILOT_GITHUB_TOKEN=github_pat_xxx

use Revolution\Copilot\Facades\Copilot;

$response = Copilot::run(prompt: 'Hello');

In TCP mode, set environment variables on the CLI server side.

Authentication priority

The SDK resolves credentials in this order:

github_token (explicitly provided)
Environment variable tokens (COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN)
OAuth credentials stored by CLI
Credentials from gh CLI

If you do not want to use stored credentials, set use_logged_in_user to false. When set to false, only the token you pass explicitly (github_token) is used for authentication. Environment variable tokens (COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN) are ignored.

use Revolution\Copilot\Facades\Copilot;

$response = Copilot::useStdio([
    'use_logged_in_user' => false,
])->run(prompt: 'Hello');

As with github_token, this is supported in stdio mode only. In TCP mode, the Copilot CLI must already be authenticated.

Check authentication status

You can read the result of auth.getStatus.

use Revolution\Copilot\Facades\Copilot;

$status = Copilot::client()->getAuthStatus();

if (! $status->isAuthenticated) {
    // Not authenticated
}

Enumerate loginAccounts through the session RPC to get the stored identities you can reuse with a given provider. Each item’s label is for display, and active indicates whether the identity matches the current session’s active account. accountId is an opaque ID owned by the provider. Pass it to the login request as is, without parsing or modifying it.

use Revolution\Copilot\Enums\AuthLoginMode;
use Revolution\Copilot\Enums\LoginProviderKind;
use Revolution\Copilot\Types\Rpc\AuthLoginBeginRequest;

$accounts = $session->rpc()->accounts();
$identities = $accounts->enumerate(
    'loginAccounts',
    provider: LoginProviderKind::ENTRA,
);

if (isset($identities[0])) {
    $accounts->begin(new AuthLoginBeginRequest(
        kind: LoginProviderKind::ENTRA,
        mode: AuthLoginMode::Default,
        accountId: $identities[0]->accountId,
    ));
}

Use mode: 'default' to reuse a stored identity with the provider’s normal behavior. Use mode: 'selectAccount' to explicitly show the provider’s account picker. In that case, don’t pass accountId. Existing calls such as begin(LoginProviderKind::ENTRA) continue to work.

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Authentication - GitHub Copilot SDK for Laravel

Authentication

Authentication methods

Microsoft Entra ID

Network callbacks

OAuth GitHub App / PAT

Mask host-generated secrets

Environment variables

Authentication priority

Check authentication status

​Authentication

​Authentication methods

​Microsoft Entra ID

​Network callbacks

​GitHub login (CLI)

​OAuth GitHub App / PAT

​Mask host-generated secrets

​Environment variables

​Authentication priority

​Disable automatic login

​Check authentication status

​Select an account for interactive login

Authentication

Authentication methods

Microsoft Entra ID

Network callbacks

GitHub login (CLI)

OAuth GitHub App / PAT

Mask host-generated secrets

Environment variables

Authentication priority

Disable automatic login

Check authentication status

Select an account for interactive login