🤖 Copilot for Business User Management API (beta)

[2percentsilk]

We've just released our beta version of the User Management API for GitHub Copilot for Business.

Note: You must authenticate using an access token with the manage_billing:copilot scope and be an admin on the Copilot for Business organization you're updating to use this endpoint.

We'd love for you to try it out and let us know what you think!

[GregoireW]

The https://api.github.com/organizations/ORG/copilot/billing endpoint give the seat breakdown. By any chance, will it be possible in the future to have a https://api.github.com/organizations/ORG/copilot/billing/detail endpoint with the list of user for each status ( "added_this_cycle", "pending_invitation", "pending_cancellation", "active_this_cycle", "inactive_this_cycle") ?

Well At least it would be nice to have the "active_this_cycle" detail for internal billing

[GregoireW]

replying myself ... an additional option with "this period" and "previous period" also will be nice.

[therzka]

@GregoireW You can hit the https://api.github.com/organizations/ORG/copilot/billing/seats https://api.github.com/orgs/ORG/copilot/billing/seats endpoint to get a list of seats in your organization. Each user in the response has a last activity date and a pending cancellation date if applicable.

[GregoireW]

Is there a billing list available ? (like i want to check which seat has been bill last month) ?

[therzka]

not at this time

and apologies for the above, the endpoint is https://api.github.com/orgs/{org}/copilot/billing/seats, we're putting in a fix for the typo in the docs

[vladholubiev]

I get a 404 response. Is this endpoint for GitHub Enterprise only or otherwise gated?

{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest"
}

UPDATE: To fix the problem do:

• Change organizations to orgs in the API path
• Make sure your token has manage_billing:copilot scope

[vladholubiev]

@Dylan-Rinker thanks! The error message is now different, but still no response

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/shelfio/copilot/billing/seats
{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest/copilot/copilot-for-business#list-all-copilot-for-business-seat-assignments-for-an-organization"
}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/shelfio/copilot/billing
{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest/copilot/copilot-for-business#get-copilot-for-business-seat-information-and-settings-for-an-organization"
}

[nielsdt-rabobank]

I had the same problem. Apparently, there is a new scope that must be added to your token. When I added that scope, it started working:
"You must authenticate using an access token with the manage_billing:copilot scope to use this endpoint."

BTW I was confused by the 404 it gave, would have expected something like 403 or so.

[vladholubiev]

@nielsdt-rabobank thanks! adding a scope to the token fixed the problem!

[2percentsilk]

Apologies for the bugs folks - we'll get the docs updated. Thank you so much for trying this out and getting this feedback to us! ❤️

[affrae]

BTW I was confused by the 404 it gave, would have expected something like 403 or so.

@nielsdt-rabobank We generally use a 404 not found as we do not want to let a drive by attacker know that the resource exists and they simply did not have access with whatever credentials they tried. 403 forbidden admits that something exists and that can be a red flag for some customers, so we take a more conservative approach.

This is a thing we do generally across the board at GitHub for privacy and security reasons. It is in line with https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3

[mntlty]

@2percentsilk I think there's a typo in the docs for 2 of the route names from https://docs.github.com/en/rest/copilot/copilot-for-business?apiVersion=2022-11-28

• https://docs.github.com/en/rest/copilot/copilot-for-business?apiVersion=2022-11-28#get-copilot-for-business-seat-information-and-settings-for-an-organization
• https://docs.github.com/en/rest/copilot/copilot-for-business?apiVersion=2022-11-28#list-all-copilot-for-business-seat-assignments-for-an-organization

these are both prefixed with /organizations/{org} which the other routes are prefixed with /orgs/{org}. With the longer path name I get a 404.

[2percentsilk]

We're updating now. thank you so much for letting us know!

[mntlty]

looks like it's fixed!

[juliettewyman]

I just took a peak at the documentation and it doesn't look like it was updated.

[therzka]

Sorry about that, looks like it reverted. Getting it updated ASAP, thanks for pointing this out!

[nielsdt-rabobank]

Great new API's! I was looking out for this one.

Question:
Would it be possible to add the "SSO Linked identity" to the https://api.github.com/orgs/ORG/copilot/billing/seats endpoint?

Background:
We have a SAML integration on our enterprise/organisation and we would prefer the SSO linked identity to show up somewhere so we can contact the inactive users directly (that is: through their corporate account email). We now only have their github id ("login") and still have to match these through a graphQL query. Would be really great if that extra step is not necessary anymore

Thanks!

[trend-yafang-qiu]

Is it possible to get below data:
How often copilot used for a user?

[dylan-asos]

We have an integration using the authenticate as a github app / installation token approach, This is a background job running from various events, no user interaction - so the IAT approach is appropriate. Up until now, this has been doing some basic team setup & maintenance.

i.e. generate a JWT using the private key associated with the app, exchange for an installation token,

public async Task<GitHubClient> GetGitHubInstallationClient()
{
    var jwtToken = PemToJwtGenerator.GenerateGithubAppJwtFromPem(_privateKey, _appId);
    var appClient = new GitHubClient(new ProductHeaderValue("MyApp"))
    {
        Credentials = new Credentials(jwtToken, AuthenticationType.Bearer)
    };
    
    var installationTokenResponse = await appClient.GitHubApps.CreateInstallationToken(_installationId);
    var installationClient = new GitHubClient(new ProductHeaderValue("MyApp"))
    {
        Credentials = new Credentials(installationTokenResponse.Token)
    };

    return installationClient;
}

I've just granted the app write permissions for 'GitHub Copilot for Business' and that scope is returned in the token, as per

Attempt to call the copilot/billing/selected_users endpoint results in,

{"message":"Seat assignment for user xxx-xxx could not be created: Inviting User is not an admin of the organization",
"documentation_url":"https://docs.github.com/rest/copilot/copilot-for-business#add-users-to-the-copilot-for-business-subscription-for-an-organization"}

OK - docs are pretty clear that the access token needs to be an admin on the org it's targeting - is the 'auth as app' flow supported in this scenario or need to change approach? If supported - what am I missing to grant the app the permissions it requires?

Thanks

[therzka]

Thanks for raising this, we're looking into it and will keep you posted!

[therzka]

Hi! We pushed a change that should resolve this issue... please try again and let me know how it goes!

[dylan-asos]

Thanks @therzka - looks good now. That really simplifies my workflow so appreciate the turnaround

[dylan-asos]

I'm calling /copilot/billing/seats to get the current list of allocated seats. I'm using the Octokit c# connection for this, e.g.

var targetUri = new Uri(_githubConnection.BaseAddress, $"orgs/{AsosTeamOrgName}/copilot/billing/seats");
            
var response = await _githubConnection.Get<AllocatedSeatsResponse>(targetUri, parameters);

This is currently throwing an exception

System.FormatException: String '2023-08-01' was not recognized as a valid DateTime.
   at System.DateTimeParse.ParseExactMultiple(ReadOnlySpan`1 s, String[] formats, DateTimeFormatInfo dtfi, DateTimeStyles style, TimeSpan& offset)
   at System.DateTimeOffset.ParseExact(String input, String[] formats, IFormatProvider formatProvider, DateTimeStyles styles)
   at Octokit.PocoJsonSerializerStrategy.DeserializeObject(Object value, Type type) in /_/Octokit/SimpleJson.cs:line 1386

Which seems due to the pending_cancellation_date field, e.g.

"pending_cancellation_date": "2023-08-01"

Seems similar to this report and issue (octokit/octokit.net#1785 (comment)), worth keeping the date format aligned with all other date responses?

[chrheg]

Would it be possible to implement the next link in the header if there is multiple pages of results ?

[therzka]

Done!

[chrheg]

The created_at field in https://docs.github.com/en/rest/copilot/copilot-for-business?apiVersion=2022-11-28#list-all-copilot-for-business-seat-assignments-for-an-organization , looks to take the date from when the Team was added. After that all users added to that team will have the same created_at value it seems. Would it be possible to get a separate field that contains when the actual user got access ?

[Dasio]

Would it be possible to change the required access for GET endpoints from write to read?

https://docs.github.com/en/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#organization-permissions-for-github-copilot-for-business

GET /orgs/{org}/copilot/billing
GET /orgs/{org}/copilot/billing/seats

[dylan-asos]

Support for the API is now available in octokit.net - https://github.com/octokit/octokit.net/releases/tag/v9.1.0

I haven't finished all the endpoints yet - but there's enough there that should enable some automated license allocation/clear up for people. Another PR to come shortly that'll finish the remaining endpoints.

[Crowelling]

Hey, do you know when it will be available for js?

[dylan-asos]

Sorry, no - not something I'm picking up - I'm only looking at the the dotnet client when time permits.

[tcooperFL]

When will we have some more helpful metrics about our organization's Copilot usage? Just giving us a csv report dump with status, team, last activity date, and last editor used isn't enough to understand what productivity gains we may be getting. Rather than use global averages, I'd like to know how my organization is using it: how many lines accepted, usage over time, activity distribution between inline suggestions and Chat features, etc. How might I get that on a team or user level, and if not yet, when might I expect to? Surely many organizations are asking this.

[djopatrny]

Hi @tcooperFL - we do receive this request, and the team is working on addressing the gap. We're looking forward to having more news to share later this quarter.

[virajkanwade]

Any update on this? Is there a ticket to track the status?

[djopatrny]

Hi @virajkanwade - In April we shipped the public beta of the Copilot Metrics API which allows you to pull data related to code completions and chat for GitHub orgs and enterprises. This summer we are introducing team-level aggregations. Our current goal is to bring these online in July.

[flaviodelgrosso]

Hi @djopatrny thanks for your work about Metrics API, it is a very hot topic specially in large companies. The team-level aggregations are very useful.
I’m curious if you plan to also offer a view of the aggregated metrics below for single user. This feature could help associate a user with a specific company project or even grouping automated hours by internal clusters and industries.

{
    "total_suggestions_count": 5000,
    "total_acceptances_count": 3000,
    "total_lines_suggested": 7000,
    "total_lines_accepted": 3500,
    "total_active_users": 15,
    "total_chat_acceptances": 45,
    "total_chat_turns": 350
}

[AyesKumar]

Hi Team
Have we, by any chance, changed the API URL for Get a summary of Copilot usage for organization members (https://docs.github.com/en/rest/copilot/copilot-usage?apiVersion=2022-11-28#get-a-summary-of-copilot-usage-for-organization-members)? I am currently encountering a 404 error with the following response message:
{
"message": "Not Found",
"documentation_url": "https://docs.github.com/rest/copilot/copilot-usage#get-a-summary-of-copilot-usage-for-organization-members",
"status": "404"
}

URL: https://api.github.com/orgs/{org_name}/copilot/usage
Alos i have provided manage_billing:copilot, read:org scopes in my token.

[tcooperFL]

This is working fine for me, and I've called it successfully each day the past 3 days.

[therzka]

No issues I can see on our end, make sure you are the administrator of the organization and that your token hasn't expired.