🤖 Copilot for Business User Management API (beta) #60780

2percentsilk · 2023-07-13T14:59:32Z

2percentsilk
Jul 13, 2023

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 · 2023-07-14T19:09:13Z

GregoireW
Jul 14, 2023

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

4 replies

GregoireW Jul 14, 2023

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

therzka Jul 14, 2023

@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 Jul 15, 2023

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

therzka Jul 17, 2023

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 · 2023-07-15T11:55:40Z

vladholubiev
Jul 15, 2023

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

6 replies

vladholubiev Jul 17, 2023

@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 Jul 17, 2023

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 Jul 17, 2023

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

2percentsilk Jul 17, 2023
Author

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 Aug 9, 2023

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 · 2023-07-16T13:23:11Z

mntlty
Jul 16, 2023

@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

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.

4 replies

2percentsilk Jul 17, 2023
Author

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

mntlty Jul 17, 2023

looks like it's fixed!

juliettewyman Jul 19, 2023

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

therzka Jul 19, 2023

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

nielsdt-rabobank · 2023-07-17T07:06:00Z

nielsdt-rabobank
Jul 17, 2023

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!

0 replies

trend-yafang-qiu · 2023-07-17T08:54:56Z

trend-yafang-qiu
Jul 17, 2023

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

0 replies

dylan-asos · 2023-07-19T20:34:16Z

dylan-asos
Jul 19, 2023

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

3 replies

therzka Jul 20, 2023

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

therzka Aug 8, 2023

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

dylan-asos Aug 24, 2023

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

dylan-asos · 2023-07-24T11:09:08Z

dylan-asos
Jul 24, 2023

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?

0 replies

chrheg · 2023-07-27T12:59:56Z

chrheg
Jul 27, 2023

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

1 reply

therzka Sep 13, 2023

Done!

chrheg · 2023-07-28T10:09:16Z

chrheg
Jul 28, 2023

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 ?

0 replies

Dasio · 2023-10-26T14:44:05Z

Dasio
Oct 26, 2023

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

0 replies

dylan-asos · 2024-01-18T14:57:13Z

dylan-asos
Jan 18, 2024

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.

2 replies

Crowelling Jan 25, 2024

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

dylan-asos Jan 28, 2024

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

tcooperFL · 2024-01-31T16:53:15Z

tcooperFL
Jan 31, 2024

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.

4 replies

djopatrny Feb 2, 2024

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 Jun 18, 2024

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

djopatrny Jun 19, 2024

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 Jun 24, 2024

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 · 2024-11-05T02:46:32Z

AyesKumar
Nov 5, 2024

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.

2 replies

tcooperFL Nov 7, 2024

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

therzka Nov 7, 2024

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

levanvunam · 2024-11-21T17:20:17Z

levanvunam
Nov 21, 2024

I tried to use the billing/seats endpoint and data seems all returned.

But the "assigning_team" of member is always missing, trying to export csv from the interface also show no team, anyone has similar problem?

0 replies

This comment was marked as off-topic.

Sign in to view

🤖 Copilot for Business User Management API (beta) #60780

Replies: 15 comments · 26 replies

2percentsilk Jul 17, 2023 Author

2percentsilk Jul 17, 2023 Author

This comment was marked as off-topic.

Replies: 15 comments 26 replies

2percentsilk Jul 17, 2023
Author

2percentsilk Jul 17, 2023
Author