docs: use organization Copilot Requests permission for server-to-server tokens

[gfarb]

Part of github/copilot#31519 (Document organization App setup, billing and token renewal)
Epic: github/copilot#30409

Summary

Updates the server-to-server guide to use the organization Copilot Requests permission (organization_copilot_requests, read-only, registered in github/github#456098 and enforced by CAPI via authzd in github/copilot-api#38896) instead of the repository permission.

• Setup: the App requests the organization Copilot Requests permission set to Read-only. An All repositories installation and repository_ids are no longer required.
• Billing: usage is billed to the organization that owns the installation. Installations on personal accounts are rejected for custom Apps, so the user-account billing clause is removed.
• Troubleshooting: replaces the repository_ids and All repositories rows with a single organization permission row. Fixes the 401 row, since CAPI returns 403 when GitHub App installation tokens are not enabled.
• Code samples: the guide set COPILOT_GITHUB_TOKEN with useLoggedInUser: false, which never authenticates. With logged-in-user fallback disabled, the runtime ignores environment variable tokens and accepts only the SDK's explicit token option. The samples now pass the installation token through gitHubToken (or the language equivalent), and the FFI, refresh and troubleshooting text, the auth README, and the authenticate.md "Disabling auto-login" section are updated to match.

Validation

Run 2026-10-08 against prod https://api.githubcopilot.com/models (no inference):

• Default installation token (no request body), selected-repositories install: 200
• Token scoped to permissions: {organization_copilot_requests: read} only: 200
• Token scoped to repository_ids only: 200
• Token missing the org permission, and App without it: 403 the GitHub App installation access token does not have the organization "Copilot Requests" read permission

Run 2026-10-12 with SDK 1.0.19 and runtime 1.0.95 on macOS, isolated from stored credentials:

• gitHubToken with useLoggedInUser: false: authenticates in TypeScript, Python and Go (child process) and in-process FFI. TypeScript createSession and inference succeed.
• COPILOT_GITHUB_TOKEN with useLoggedInUser: false: Not authenticated (child process) and No GitHub OAuth token or Copilot HMAC key provided (FFI).
• Existing runtime URI with COPILOT_GITHUB_TOKEN set on the runtime process: authenticates.
• Refresh: after revoking a token, a new client with the old token gets 401 and a new client with a new token works.
• Token without the Copilot Requests permission: 403.

Not yet validated: Rust, .NET and Java samples (API names checked against SDK source only), and the "not enabled" troubleshooting row.

[Copilot]

🟡 Changes recommended

The guidance incorrectly generalizes explicit SDK tokens to external URI runtimes, which require process-level authentication.

2 open findings

• Document existing-runtime URI authentication exception · New
• Clarify token options are unsupported for existing-runtime URI connections · New

What changed in this PR

Updates server-to-server authentication guidance to use organization-level Copilot permissions and explicit SDK token options.

Changes:

• Uses read-only organization Copilot Requests permission.
• Updates token configuration examples across six SDKs.
• Revises billing, renewal, and troubleshooting guidance.

File	Description
docs/​auth/​server-to-server-tokens.md	Updates App setup, samples, billing, and troubleshooting.
docs/​auth/​README.md	Revises installation-token authentication guidance.
docs/​auth/​authenticate.md	Clarifies disabled credential fallback behavior.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.