Billing API access: Can a Billing Manager's UAT access the billing usage endpoint?

[subhammahanty235]

Select Topic Area

Question

Body

Title: Does Billing Manager role include "Administration" org permission for API access?

Body:

Quick question about the billing API endpoint:
GET /organizations/{org}/settings/billing/usage

The docs say this requires "Administration" organization permissions (read).

Question: Does the Billing Manager role include this "Administration" permission?

Context:

• Billing Managers can view billing in the GitHub web UI ✓
• Can a Billing Manager's User Access Token (UAT) call the billing API? ✓ or ✗
• Or must the token come from an Organization Owner?

Why I'm asking:
Building a SaaS app that needs billing data. Trying to decide between:

• GitHub App with IAT (requires Owner to install)
• GitHub App with UAT (requires user to authorize OAuth)

If UAT also requires an Owner (because only Owner has "Administration" permission),
then both approaches have the same requirement, and IAT seems more robust.

Thanks!

[easwar16]

Hey @subhammahanty235,

Short answer: No. The Billing Manager role does not include the "Administration" organization permission required for the billing usage API.

The endpoint:

GET /organizations/{org}/settings/billing/usage

requires the "Administration" organization permission (read). This permission is only granted to Organization Owners or to tokens that explicitly have the Administration scope through an app installation or owner-authorized token.

Role capabilities

Billing Manager:

• Can view billing information in the GitHub web UI
• Can manage payment methods and billing settings
• Does NOT receive the "Administration" org permission

Organization Owner:

• Has full administrative permissions
• Includes the required "Administration" permission needed by the billing API

API implications

A Billing Manager's User Access Token (UAT) will generally NOT be able to call this endpoint because the token does not carry the required Administration permission.

To access the billing usage API you typically need one of the following:

1. A GitHub App installation token (IAT) where the app has been granted the required organization-level permissions and installed by an Organization Owner.

2. A user token belonging to an Organization Owner that has the required admin scope.

Architecture recommendation

For SaaS integrations that need billing data across organizations, a GitHub App using an Installation Access Token (IAT) is usually the preferred approach because:

• Permissions are explicit and scoped
• Installation is authorized once by the Organization Owner
• Tokens can be generated programmatically
• It avoids relying on individual user tokens

Summary

Billing Manager → Can view billing in the UI but cannot call the billing usage API.

Organization Owner → Has the Administration permission required for the API.

For programmatic access to billing usage data, a GitHub App with an Installation Access Token installed by an Organization Owner is typically the correct approach.

[ash-iiiiish]

Here is the detailed breakdown to confirm this and help you decide on your SaaS app's architecture:

1. Billing Manager vs. API Permissions
   While a Billing Manager can view billing info in the web UI , the REST API operates under a different permission model. To access organization-level billing endpoints, the authenticated user (or token) needs the "Administration" organization permission (read) .

The Conflict: The Billing Manager role is specifically scoped to enterprise billing settings and does not grant the "Administration" permission at the organization level .

The Requirement: The "Administration" permission is a high-level privilege typically reserved for Organization Owners .

2. Answer to Your Specific Questions
   Can a Billing Manager's User Access Token (UAT) call the billing API? ✗ No. The token lacks the required "Administration" scope.

Must the token come from an Organization Owner? ✓ Yes. An Organization Owner possesses the necessary "Administration" permission.

3. Recommendation for Your SaaS App
   You are correct in your assessment. Since both a GitHub App (using an Installation Access Token) and a User Access Token (from a Billing Manager) ultimately require a highly privileged user (Owner) to authorize or install the app, the requirement is the same.

However, your conclusion that an Installation Access Token (IAT) is more robust is the right architectural choice for the following reasons:

Machine-to-Machine Communication: IATs are designed for apps that need to act independently of a specific user. Since you need to pull billing data programmatically, an IAT is more reliable (it doesn't expire based on user session/logins) .

Permission Scope: You can grant the GitHub App the specific "Administration" (read) permission at the organization level. Once an Organization Owner installs the app and grants these permissions, the app can access the billing API for that organization without further user intervention .

OAuth vs. Installation:

GitHub App with UAT: Requires every user to have the "Administration" role and authorize the app via OAuth. This creates friction and fails if a Billing Manager tries to use it.

GitHub App with IAT: Requires one Organization Owner to install the app once. After that, your application's backend can use the IAT to access the API for that organization seamlessly.

Conclusion: Proceed with the GitHub App with Installation Access Token (IAT) . It provides a more stable and secure architecture for accessing sensitive billing data compared to relying on individual user tokens.