Skip to content

Clarify BYOK token usage and limitations #402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
patniko merged 1 commit into from
Feb 7, 2026
+6 −2
Merged

Clarify BYOK token usage and limitations #402

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/auth/byok.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,19 +272,23 @@ provider: {
}
```

> **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The note says expired bearer tokens require creating a new session. However, all SDKs support resuming a session with a new provider config (e.g., ResumeSessionConfig.Provider), which can be used to supply an updated bearerToken without changing the session ID. Consider rewording to say you must reconnect (create or resume) with a fresh token, rather than implying only new sessions work.

This issue also appears on line 291 of the same file.

Suggested change
> **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.
> **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to reconnect (create a new session or resume an existing one) with a fresh token.

Copilot uses AI. Check for mistakes.
## Limitations

When using BYOK, be aware of these limitations:

### Identity Limitations

BYOK authentication is **key-based only**. The following identity providers are NOT supported:
BYOK authentication uses **static credentials only**. The following identity providers are NOT supported:

- ❌ **Microsoft Entra ID (Azure AD)** - No support for Entra managed identities or service principals
- ❌ **Third-party identity providers** - No OIDC, SAML, or other federated identity
Comment on lines +283 to 286
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section says Microsoft Entra ID is “NOT supported,” but the page also explains that Entra can issue bearer tokens and the SDK can accept a static bearerToken string. To avoid contradicting yourself, consider clarifying that Entra/managed identity/service principal token acquisition and automatic refresh are not supported by the SDK (but users may supply Entra-issued tokens if they manage refresh themselves).

See below for a potential fix:

BYOK authentication uses **static credentials only**. The SDK does not have built-in integrations with identity providers for token acquisition or automatic refresh:

- ❌ **Microsoft Entra ID (Azure AD)** - No built-in support for Entra managed identities or service principals (no automatic token acquisition/refresh)
- ❌ **Third-party identity providers** - No built-in OIDC, SAML, or other federated identity integrations
- ❌ **Managed identities** - No automatic token acquisition via Azure Managed Identity or similar mechanisms

You must use an API key or static bearer token that you manage yourself.

**Why not Entra ID?** While Entra ID does issue bearer tokens, these tokens are short-lived (typically 1 hour) and require automatic refresh via the Azure Identity SDK. The `bearerToken` option only accepts a static string—there is no callback mechanism for the SDK to request fresh tokens. Entra-issued bearer tokens can be used with BYOK as long as you acquire and refresh them yourself and create new sessions with updated tokens. For long-running workloads requiring Entra authentication, you must implement your own token acquisition/refresh logic outside the SDK.

Copilot uses AI. Check for mistakes.
- ❌ **Managed identities** - Azure Managed Identity is not supported

You must use an API key or bearer token that you manage yourself.
You must use an API key or static bearer token that you manage yourself.

**Why not Entra ID?** While Entra ID does issue bearer tokens, these tokens are short-lived (typically 1 hour) and require automatic refresh via the Azure Identity SDK. The `bearerToken` option only accepts a static string—there is no callback mechanism for the SDK to request fresh tokens. For long-running workloads requiring Entra authentication, you would need to implement your own token refresh logic and create new sessions with updated tokens.

### Feature Limitations

Expand Down