GitHub Personal Access Token Requirements for the GitHub Copilot API

A development team running automated user provisioning scripts will see their GitHub Copilot API integration fail with a 404 error if their authentication token lacks the specific administrative version header, even if they have configured the correct permissions. The GitHub Copilot API requires personal access tokens with explicit administrative or billing scopes to authorize programmatic seat and usage management. Organizations managing developer tools must secure credential access while maintaining automated provisioning systems. Because Copilot access is tied directly to subscription costs, GitHub gates these endpoints behind scopes that prevent unauthorized access. When configuring integration scripts or custom tooling, developers must decide between two credential pathways: classic Personal Access Tokens (PATs) or fine-grained PATs.

Fine-grained tokens permit repository-level or account-level scoped credentials, which follows the security principle of least privilege. Classic tokens rely on account-wide scopes like manage_billing:copilot, which grants broader access to account billing settings. Understanding how to navigate these permissions prevents authentication failures and protects the integrity of your organization's subscription data.

The separation between organization-level and enterprise-level scopes is a key design aspect of the GitHub REST API. Organization owners manage seats for their specific organization, whereas enterprise owners manage policies and licenses across multiple organizations. If you attempt to access an enterprise billing endpoint with an organization-scoped token, the API will reject the request. Similarly, an enterprise owner cannot manage individual seats within an organization without having organization-level privileges. This architectural boundary ensures that large companies can delegate day-to-day seat management to individual team leads while keeping billing controls centralized.

Assigning Copilot seats programmatically is particularly important for large teams. While manual assignment through the web interface is feasible for a small team, it quickly becomes unmanageable as the organization grows. Data shows that 80% of new developers on GitHub use Copilot within their first week, making AI-assisted coding a default onboarding expectation. By automating seat management, teams can ensure that developers receive immediate access upon onboarding, and that licenses are reclaimed when a developer departs. This automation relies on script integrations that must run continuously and securely, highlighting the importance of properly configured API tokens.

• OpenAI Codex Usage Limits: API Tiers, Rate Caps, and Token BudgetsOpenAI Codex usage limits are tier-based rate caps (requests per minute and tokens per minute) and monthly spending...
• How to Use the Manus AI API for Agent TasksFiles uploaded through the Manus API are automatically deleted 48 hours after upload, so production integrations need...
• GitHub Copilot API Developer Guide: Uptime, Metrics, and Agent IntegrationAn in-depth developer guide to the GitHub Copilot REST API. Learn how to manage seats programmatically, download daily...
• GitHub Personal Access Token vs. Fine-Grained Token for GitHub CopilotChoosing between classic and fine-grained personal access tokens determines the security boundary of GitHub Copilot CLI...
• GitHub Copilot Personal Access Token Permissions for MCPSetting up a GitHub Model Context Protocol (MCP) server with administrative credentials exposes your entire account...
• How to Generate a GitHub Personal Access Token for Copilot and AI AgentsConnecting coding agents to your repositories requires secure authentication. Fine-grained personal access tokens...

More on this subject: GitHub Copilot (130 guides)

When configuring your automation scripts, you need to map each endpoint to the correct credential permissions. Classic PAT scopes are account-wide, meaning that granting a classic token permission to manage billing exposes other billing settings for the entire organization. Fine-grained permissions restrict access to specific organizations or repositories.

Below is a detailed breakdown of the required credentials for each primary Copilot endpoint:

• The API endpoint is GET /orgs/{org}/copilot/billing. The action retrieves Copilot billing information for an organization. Using a classic token requires manage_billing:copilot and read:org scopes. Using a fine-grained token requires "GitHub Copilot Business" (Read) or "Administration" (Read) organization permissions.

• The API endpoint is GET /orgs/{org}/copilot/billing/seats. The action lists all Copilot seat assignments for an organization. Using a classic token requires manage_billing:copilot and read:org scopes. Using a fine-grained token requires "GitHub Copilot Business" (Read) or "Administration" (Read) organization permissions.

• The API endpoint is POST /orgs/{org}/copilot/billing/selected_users. The action adds users to the Copilot subscription for an organization. Using a classic token requires manage_billing:copilot or admin:org scopes. Using a fine-grained token requires "GitHub Copilot Business" (Write) or "Administration" (Write) organization permissions.

• The API endpoint is DELETE /orgs/{org}/copilot/billing/selected_users. The action removes users from the Copilot subscription. Using a classic token requires manage_billing:copilot or admin:org scopes. Using a fine-grained token requires "GitHub Copilot Business" (Write) or "Administration" (Write) organization permissions.

• The API endpoint is GET /orgs/{org}/copilot/usage. The action retrieves Copilot usage metrics for an organization. Using a classic token requires manage_billing:copilot and read:org scopes. Using a fine-grained token requires "GitHub Copilot Business" (Read) or "Administration" (Read) organization permissions.

• The API endpoint is GET /enterprises/{enterprise}/copilot/billing. The action retrieves Copilot billing information for an enterprise. Using a classic token requires manage_billing:copilot and read:enterprise scopes. Using a fine-grained token requires "Enterprise AI controls" enterprise permissions (Read).

• The API endpoint is GET /enterprises/{enterprise}/copilot/usage. The action retrieves Copilot usage metrics for an enterprise. Using a classic token requires manage_billing:copilot and read:enterprise scopes. Using a fine-grained token requires "Enterprise Copilot metrics" enterprise permissions (Read).

Choosing between these token types depends on your security policy. If your organization is part of an enterprise, using fine-grained tokens is recommended because it restricts the token to specific repositories or organizations. Classic tokens should only be used when integrating with legacy systems that do not support fine-grained permissions.

To generate a personal access token for the Copilot API, you must navigate through GitHub's developer settings. The process varies slightly depending on whether you are configuring a classic token or a fine-grained token.

To configure a classic Personal Access Token:

1. Log in to your GitHub account, open your profile menu in the top-right corner, and select Settings.
2. Scroll to the bottom of the left sidebar and click Developer settings.
3. In the developer settings menu, select Personal access tokens, then click Tokens (classic).
4. Click Generate new token, and select Generate new token (classic).
5. Give your token a descriptive note, such as "Copilot Seat Management Automation Script".
6. Set the expiration date according to your security policy.
7. Under Select scopes, locate the manage_billing:copilot checkbox and check it. Also select read:org if you only need read access, or admin:org if you need to modify seat assignments.
8. Click Generate token at the bottom of the page, and copy the token immediately.

To configure a fine-grained Personal Access Token:

1. Open Developer settings and select Personal access tokens, then click Fine-grained tokens.
2. Click Generate new token.
3. Provide a name and expiration date for your token.
4. Under Resource owner, select the organization that holds your Copilot subscription.
5. Under Repository access, select All repositories if your scripts manage repository settings, or select Only select repositories to limit access.
6. Under Organization permissions, locate the "GitHub Copilot Business" row and select Read-only or Read and write from the dropdown.
7. Click Generate token and copy the generated credentials.

In addition to token scopes, every request made to the GitHub REST API must include the correct API version header. GitHub requires the X-GitHub-Api-Version header set to 2022-11-28 for all requests. Omitting this header is the most common reason for unexpected 404 responses. The API uses date-based versioning, and specifying this header guarantees that your scripts interact with the stable version of the endpoints. If you update your scripts in the future, you must review the version requirements to ensure that your payload formats remain compatible with newer API updates.

Store and search your Copilot automation scripts in one place

Provide your engineering team with a shared workspace for API configuration files and usage data. Every organization starts with a 14-day free trial on a paid subscription.

Start 14-Day Trial

Automating seat provisioning requires writing scripts that execute API calls securely. When executing these scripts, the token must be passed as a bearer credential in the authorization header. Below is an example of how to make an authenticated request using a standard curl command.

curl -L \
  -X POST \
  -H \"Accept: application/vnd.github+json\" \
  -H \"Authorization: Bearer your-github-token\" \
  -H \"X-GitHub-Api-Version: 2022-11-28\" \
  https://api.github.com/orgs/my-organization/copilot/billing/selected_users \
  -d '{\"selected_usernames\":[\"developer1\", \"developer2\"]}'

In this request, the Accept header specifies the GitHub JSON format, the Authorization header carries the token, and the X-GitHub-Api-Version header ensures compatibility. The payload contains a list of usernames to be assigned a seat. A successful request returns a JSON response outlining the assignment details, including the status of each user.

If you are using Python to build your automation, you can use the requests library to handle authentication. The following script lists all current seat assignments and prints the last activity time for each user.

import os
import requests

token = os.environ.get(\"GITHUB_TOKEN\")
headers = {
    \"Accept\": \"application/vnd.github+json\",
    \"Authorization\": f\"Bearer {token}\",
    \"X-GitHub-Api-Version\": \"2022-11-28\"
}
url = \"https://api.github.com/orgs/my-organization/copilot/billing/seats\"

response = requests.get(url, headers=headers)
if response.status_code == 200:
    seats_data = response.json()
    for seat in seats_data.get(\"seats\", []):
        username = seat.get(\"assignee\", {}).get(\"login\")
        last_activity = seat.get(\"last_activity_at\")
        print(f\"User: {username} | Last Activity: {last_activity}\")
else:
    print(f\"Error: {response.status_code} - {response.text}\")

Using python scripts allows your team to integrate Copilot seat management with other internal directories or human resource platforms. By checking the last_activity_at field, you can identify accounts that have not used the tool for several weeks. This allows you to programmatically reclaim seats, optimizing subscription costs by reducing unused licenses. Since Copilot licenses are charged per active seat, automating this cleanup loop directly reduces unnecessary IT expenditures.

Managing API configurations, credentials, and script templates requires a reliable storage solution. Many teams default to local directories, AWS S3 buckets, or general cloud drives like Google Drive. However, these tools are built for human file sync and lack the intelligence needed for agentic automation and secure sharing. They do not index contents for meaning-based search or allow agents to easily read and write data.

Fast.io provides a dedicated workspace for agentic teams. By organizing your scripting files, credentials, and Copilot usage metrics in a shared workspace, both humans and software agents can access the same context. When you upload your usage report or API scripts, Fast.io automatically indexes them for hybrid search, combining full-text and semantic search, and RAG chat.

This means you can query your workspace using the remote MCP server located at https://mcp.fast.io/mcp/code over Streamable HTTP, where interactive clients sign in with OAuth in the browser and headless code sends an Authorization: Bearer <api key> header (see Fast.io documentation), or run operations using the @vividengine/fastio-cli CLI. For example, a coding agent can read your Copilot configuration templates, execute local commands to test the credentials, and update the version history directly. This persistent environment ensures that all automation assets remain versioned and audited.

Every organization starts with a 14-day free trial, which requires a credit card to activate. Fast.io offers three simple paid plans: Starter ($9.99/mo), Business ($49.99/mo), and Enterprise ($199.99/mo). Doing real work requires a paid subscription, which includes seat-level access and auto-indexing features to help your team coordinate.

Using Fast.io's workspaces also allows teams to maintain clear logs of who modified specific scripts. When an agent updates a provisioning script, the change is recorded in the append-only audit log. The human team lead can inspect the real-time activity feed, review the version history, and transfer ownership of the scripts to other team members when needed. This combination of persistent storage for agents and agent-friendly API access bridges the gap between raw code files and automated operations.