You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Preview the upcoming organization permission changes
4
+
created_at: 2014-12-08
5
+
author_name: jakeboxer
6
+
---
7
+
We have some upcoming changes that will affect the way organization members and repositories are managed. The most important changes are:
8
+
9
+
- The Owners team will no longer be special.
10
+
- The [List your repositories][list-your-repos] API will include organization-owned repositories.
11
+
- The [List user organizations][list-user-organizations] API will only include public organization memberships.
12
+
13
+
## What's happening to the Owners team?
14
+
15
+
Currently, members of your Owners team are administrators of your organization. Soon, your Owners team will become a totally normal team. Adding and removing Owners team members won't change their administrator status anymore. Instead, you'll be able to directly grant admin permissions to your organization's members without adding them to any special teams.
16
+
17
+
We won't delete your Owners team, but you'll be able to delete or rename it yourself if you want. Organizations created after the change won't have an Owners team.
18
+
19
+
### What should you do?
20
+
21
+
In preparation for this change to the Owners team, we're releasing a few new APIs. You'll be able to use these APIs to manage organization admins without relying on the Owners team.
22
+
23
+
#### Adding an organization admin
24
+
25
+
To add a new organization admin, use the new [Add or update organization membership][add-org-membership] endpoint, specifying a role of `"admin"` in the request body. This replaces adding or inviting people to the Owners team.
26
+
27
+
#### Removing an organization admin
28
+
29
+
To remove someone from the organization role but keep them as a member of their teams, use the new [Add or update organization membership][add-org-membership] endpoint, specifying a role of `"member"` in the request body. This replaces removing people from the Owners team.
30
+
31
+
#### Listing organization admins
32
+
33
+
To get a list of all your organization's admins, use the [Organization members list][list-org-members] endpoint, specifying a role of `"admin"` in the query string. This replaces listing the members of the Owners team.
34
+
35
+
#### Checking if someone is an organization admin
36
+
37
+
To check if a given user is an organization admin, use the new [Get organization membership][get-org-membership] endpoint. If the returned `"role"` attribute is set to `"admin"` and the returned `"state"` attribute is set to `"active"`, the user is an organization admin. This replaces checking if a user is on the Owners team.
38
+
39
+
## What's happening to the "List your repositories" API?
40
+
41
+
Currently, the [List your repositories][list-your-repos] API only returns repositories that are owned by users, not by organizations. If you want a list of *all* the repositories that the authenticated user has access to, you need to use multiple API methods.
42
+
43
+
Soon, this API will include all repositories that the authenticated user has access to (whether they're owned by a user or by an organization).
44
+
45
+
### What should you do?
46
+
47
+
Many apps use the [List your repositories][list-your-repos] API in conjunction with the [List your organizations][list-your-orgs] and [List organization repositories][list-org-repos] APIs to build up a list of all the repositories the authenticated user has access to. If your app is doing this, you'll be able to get rid of all the organization-related API calls and just use the [List your repositories][list-your-repos] API.
48
+
49
+
If your app uses the [List your repositories][list-your-repos] API for another purpose, you'll need to update your app to handle the new organization-owned repositories we'll be returning.
50
+
51
+
## What's happening to the "List user organizations" API?
52
+
53
+
The [List user organizations][list-user-organizations] API is intended provide [public organization memberships][public-org-membership] for any user. When you use this API to fetch *your own* organizations, this API currently returns your public and private organization memberships.
54
+
55
+
Soon, this API will only return public organization memberships.
56
+
57
+
### What should you do?
58
+
59
+
If your app uses the [List user organizations][list-user-organizations] API to fetch all of the organization memberships (public and private) for the authenticated user, you'll need to update your app to use the [List your organizations][list-your-organizations] API instead. The [List your organizations][list-your-organizations] API returns all organizations (public and private) that your app is authorized to access.
60
+
61
+
## Preview period
62
+
63
+
Starting **today**, these new APIs are available for developers to preview. We expect the preview period to last for four weeks. (Stay tuned to the developer blog for updates.) At the end of the preview period, these additions will become official components of the GitHub API.
64
+
65
+
While these additions are in their preview period, you'll need to provide the following custom media type in the `Accept` header:
66
+
67
+
application/vnd.github.moondragon-preview+json
68
+
69
+
During the preview period, we may change aspects of these endpoints. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.
70
+
71
+
## Migration period
72
+
73
+
At the end of the preview period, we will announce the start of a migration period. At that time, developers should update their applications to use the new APIs for managing organization admins. During this period, you will still be able to use the Owners team to manage your organization's admins, so that you have time to update your applications to use the new APIs without breakage. We expect the migration period to last for four weeks.
74
+
75
+
At the end of the migration period, the Owners team will no longer be special, and you'll no longer be able to rely on it for managing organization admins.
76
+
77
+
If you have any questions or feedback, please [get in touch with us][contact]!
Copy file name to clipboardExpand all lines: content/v3/orgs.md
+22-1Lines changed: 22 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,10 @@ title: Organizations | GitHub API
11
11
12
12
List organizations for the authenticated user.
13
13
14
+
### OAuth scope requirements
15
+
16
+
When using [OAuth](/v3/oauth/#scopes), authorizations must include `user` scope or `read:org` scope.
17
+
14
18
GET /user/orgs
15
19
16
20
### Response
@@ -20,7 +24,24 @@ List organizations for the authenticated user.
20
24
21
25
## List user organizations
22
26
23
-
If you make an unauthenticated call, you will list all [public memberships](https://help.github.com/articles/publicizing-or-concealing-organization-membership) in organizations for any user. If you make an authenticated call, you will also list hidden memberships in organizations, but only for the currently authenticated user.
27
+
List [public organization memberships](https://help.github.com/articles/publicizing-or-concealing-organization-membership) for the specified user.
28
+
29
+
Currently, if you make an authenticated call, you can also list your private memberships in organizations (but only for the currently authenticated user).
30
+
31
+
With the new Organization Permissions API (described below), this method will only list *public* memberships, regardless of authentication. If you need to fetch all of the organization memberships (public and private) for the authenticated user, use the [List your organizations](#list-your-organizations) API instead.
32
+
33
+
<divclass="alert">
34
+
<p>
35
+
The Organization Permissions API is currently available for developers to preview.
36
+
During the preview period, the API may change without notice.
37
+
Please see the <a href="/changes/2014-12-08-organization-permissions-api-preview/">blog post</a> for full details.
38
+
</p>
39
+
40
+
<p>
41
+
To access the API during the preview period, you must provide a custom <a href="/v3/media">media type</a> in the <code>Accept</code> header:
Copy file name to clipboardExpand all lines: content/v3/orgs/members.md
+110-2Lines changed: 110 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,9 +21,23 @@ be returned.
21
21
Name | Type | Description
22
22
--------|---------|--------------
23
23
`filter`|`string` | Filter members returned in the list. Can be one of:<br/>*`2fa_disabled`: Members without [two-factor authentication][2fa-blog] enabled. Available for owners of organizations with private repositories.<br/>*`all`: All members the authenticated user can see.<br/><br/>Default: `all`
24
+
`role` |`string` | Filter members returned by their role. If specified, must be set to `admin`, which will only return users with admin permissions on the org. **This parameter requires a custom media type to be specified. Please see more in the alert below.**
In order to create or update a user's membership with an organization, the authenticated user must be an organization admin.
183
+
184
+
PUT /orgs/:org/memberships/:username
185
+
186
+
### Parameters
187
+
188
+
Name | Type | Description
189
+
------|--------|--------------
190
+
`role`|`string`| **Required**. The role to give the user in the organization. Can be one of:<br/> * `admin` - The user will become an administrator of the organization.<br/> * `member` - The user will become a non-admin member of the organization. Use this only to demote an existing admin to a non-admin.
191
+
192
+
### Response if user was previously unaffiliated with organization
193
+
194
+
<%= headers 200 %>
195
+
<%= json(:pending_admin_org_membership) %>
196
+
197
+
### Response if user already had membership with organization
198
+
199
+
<%= headers 200 %>
200
+
<%= json(:active_admin_org_membership) %>
201
+
202
+
## Remove organization membership
203
+
204
+
<divclass="alert">
205
+
<p>
206
+
The Organization Permissions API is currently available for developers to preview.
207
+
During the preview period, the API may change without notice.
208
+
Please see the <a href="/changes/2014-12-08-organization-permissions-api-preview/">blog post</a> for full details.
209
+
</p>
210
+
211
+
<p>
212
+
To access the API during the preview period, you must provide a custom <a href="/v3/media">media type</a> in the <code>Accept</code> header:
In order to remove a user's membership with an organization, the authenticated user must be an organization admin.
218
+
219
+
DELETE /orgs/:org/memberships/:username
220
+
221
+
If the specified user is an active member of the organization, this will remove them from the organization. If the specified user has been invited to the organization, this will cancel their invitation.
0 commit comments