kind:change

title:API enhancements for working with organization permissions are now official

created_at:2016-01-05

author_name:jakeboxer

To allow API developers to take advantage of the[improved organization permissions][dotcom-blog-post] that launched in September 2015, we're making the[API enhancements][api-enhancements-blog-post] for working with organization permissions a part of the official GitHub API.

During the preview period, you needed to[provide a custom media type in the`Accept` header][preview-period] to opt-in to the changes. Now that the preview period has ended, you no longer need to specify this custom[media type][custom-media-types].

If you have any questions or feedback, please[get in touch with us][contact]!

[dotcom-blog-post]:https://github.com/blog/2064-new-organization-permissions-now-available

[api-enhancements-blog-post]:/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/

[preview-period]:/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/#preview-period

[custom-media-types]:/v3/media/

[contact]:https://github.com/contact?form[subject]=Organization+Permissions+API

Name | Type | Description

--------|---------|--------------

`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 organization owners.<br/>*`all`: Allorganizationmembers.<br/><br/>Default:`all`

`role` |`string` | Filter members returned by their role. Can be one of:<br/>*`all`: All members of the organization, regardless of role.<br/>*`admin`: Organization owners.<br/>*`member`: Non-owner organization members.**This option requires a custom media type to be specified. Please see more in the alert below.**<br/><br/>Default:`all`

`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 organization owners.<br/>*`all`: All members the authenticated user can see.<br/><br/>Default:`all`

`role` |`string` | Filter members returned by their role. Can be one of:<br/>*`all`: All members of the organization, regardless of role.<br/>*`admin`: Organization owners.<br/>*`member`: Non-owner organization members.<br/><br/>Default:`all`

[2fa-blog]:https://github.com/blog/1614-two-factor-authentication

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see[the blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

{{/tip}}

<%= headers 200,:pagination => default_pagination_rels %>

`description`|`string` | The description of the team.

`repo_names`|`array` of`strings` | The full name (e.g., "organization-name/repository-name") of repositories to add the team to.

`privacy`|`string`| The level of privacy this team should have. Can be one of:<br/> *`secret` - only visible to organization owners and members of this team.<br/> *`closed` - visible to all members of this organization.<br/>Default:`secret`<br/>**This parameter requires a custom media type to be specified. Please see more in the alert below.**

`permission`|`string` |**Deprecated**. In the preview period described in the alert below, a team's`permission` attribute no longer dictates what permission it has on its repositories; it only dictates what permission the repositories in this request will be added with, and what permission a new repository will be added to the team with if none is specified by the user. Avoid confusion by specifying a`permission` when using the[Add team repository](/v3/orgs/teams/#add-team-repository) API instead.<br/><br/>The permission to grant the team. Can be one of:<br/> *`pull` - team members can pull, but not push to or administer these repositories.<br/> *`push` - team members can pull and push, but not administer these repositories.<br/> *`admin` - team members can pull, push and administer these repositories.<br/>Default:`pull`

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

**Warning:** If you specify the`privacy` attribute on an organization that hasn't had[improved organization permissions](https://github.com/blog/2020-improved-organization-permissions) enabled yet, you will get a`422` error response.

{{/tip}}

`permission`|`string` |**Deprecated**. The permission that new repositories will be added to the team with when none is specified. Can be one of:<br/> *`pull` - team members can pull, but not push to or administer newly-added repositories.<br/> *`push` - team members can pull and push, but not administer newly-added repositories.<br/> *`admin` - team members can pull, push and administer newly-added repositories.<br/>Default:`pull`

<%= json\

-----|------|--------------

`name`|`string` |**Required**. The name of the team.

`description`|`string` | The description of the team.

`privacy`|`string`| The level of privacy this team should have. Can be one of:<br/> *`secret` - only visible to organization owners and members of this team.<br/> *`closed` - visible to all members of this organization.<br/>Default:`secret`<br/>**This parameter requires a custom media type to be specified. Please see more in the alert below.**

`permission`|`string` |**Deprecated**. In the preview period described in the alert below, a team's`permission` attribute no longer dictates what permission it has on its repositories; it only dictates what permission a new repository will be added to the team with if none is specified by the user. Avoid confusion by specifying a`permission` when using the[Add team repository](/v3/orgs/teams/#add-team-repository) API instead.<br/><br/>The permission to grant the team. Can be one of:<br/> *`pull` - team members can pull, but not push to or administer these repositories.<br/> *`push` - team members can pull and push, but not administer these repositories.<br/> *`admin` - team members can pull, push and administer these repositories. Default:`pull`

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

**Warning:** If you specify the`privacy` attribute on an organization that hasn't had[improved organization permissions](https://github.com/blog/2020-improved-organization-permissions) enabled yet, you will get a`422` error response.

{{/tip}}

`privacy`|`string`| The level of privacy this team should have. Can be one of:<br/> *`secret` - only visible to organization owners and members of this team.<br/> *`closed` - visible to all members of this organization.<br/>Default:`secret`<br/>

`permission`|`string` |**Deprecated**. The permission that new repositories will be added to the team with when none is specified. Can be one of:<br/> *`pull` - team members can pull, but not push to or administer newly-added repositories.<br/> *`push` - team members can pull and push, but not administer newly-added repositories.<br/> *`admin` - team members can pull, push and administer newly-added repositories.<br/>Default:`pull`

Name | Type | Description

-----|------|--------------

`role`|`string`| Filters members returned by their role in the team. Can be one of:<br/> *`member` - normal members of the team.<br/> *`maintainer` - team maintainers.<br/> *`all` - all members of the team.<br/>Default:`all`<br/>**This parameter requires a custom media type to be specified. Please see more in the alert below.**

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

{{/tip}}

`role`|`string`| Filters members returned by their role in the team. Can be one of:<br/> *`member` - normal members of the team.<br/> *`maintainer` - team maintainers.<br/> *`all` - all members of the team.<br/>Default:`all`

Name | Type | Description

-----|------|--------------

`role`|`string`| The role that this user should have in the team. Can be one of:<br/> *`member` - a normal member of the team.<br/> *`maintainer` - a team maintainer. Able to add/remove other team members, promote other team members to team maintainer, and edit the team's name and description.<br/>Default:`member`<br/>**This parameter requires a custom media type to be specified. Please see more in the alert below.**

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

**Warning:** If you specify the`role` attribute on an organization that hasn't had[improved organization permissions](https://github.com/blog/2020-improved-organization-permissions) enabled yet, you will get a`422` error response.

{{/tip}}

`role`|`string`| The role that this user should have in the team. Can be one of:<br/> *`member` - a normal member of the team.<br/> *`maintainer` - a team maintainer. Able to add/remove other team members, promote other team members to team maintainer, and edit the team's name and description.<br/>Default:`member`

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

{{/tip}}

You can also get information about the specified repository, including what

permissions the team grants on it, by passing the following custom

[media type](/v3/media/) via the`Accept` header:

<%= headers 200 %>

<%= json:repo %>

Name | Type | Description

-----|------|--------------

`permission`|`string` | The permission to grant the team on this repository. Can be one of:<br/> *`pull` - team members can pull, but not push to or administer this repository.<br/> *`push` - team members can pull and push, but not administer this repository.<br/> *`admin` - team members can pull, push and administer this repository.<br/><br/>If no permission is specified, the team's`permission` attribute will be used to determine what permission to grant the team on this repository.<br/><br/>**This parameter requires a custom media type to be specified. Please see more in the alert below.**

`permission`|`string` | The permission to grant the team on this repository. Can be one of:<br/> *`pull` - team members can pull, but not push to or administer this repository.<br/> *`push` - team members can pull and push, but not administer this repository.<br/> *`admin` - team members can pull, push and administer this repository.<br/><br/>If no permission is specified, the team's`permission` attribute will be used to determine what permission to grant the team on this repository.

<%= fetch_content(:optional_put_content_length) %>

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

**Warning:** If you specify the`permission` attribute on an organization that hasn't had[improved organization permissions](https://github.com/blog/2020-improved-organization-permissions) enabled yet, you will get a`422` error response.

{{/tip}}

<%= headers 204 %>

<%= headers 200,:pagination => default_pagination_rels %>

<%= json(:user) { |h|[h] } %>

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

{{/tip}}

<%= headers 200,:pagination => default_pagination_rels %>

<%= json(:collaborator) { |h|[h] } %>

Name | Type | Description

-----|------|--------------

`permission`|`string` | The permission to grant theteam.**Only valid on organization-owned repositories.** Can be one of:<br/> *`pull` - can pull, but not push to or administer this repository.<br/> *`push` - can pull and push, but not administer this repository.<br/> *`admin` - can pull, push and administer this repository.<br/>Default:`push`<br/>**This parameter requires a custom media type to be specified. Please see more in the alert below.**

`permission`|`string` | The permission to grant thecollaborator.**Only valid on organization-owned repositories.** Can be one of:<br/> *`pull` - can pull, but not push to or administer this repository.<br/> *`push` - can pull and push, but not administer this repository.<br/> *`admin` - can pull, push and administer this repository.<br/>Default:`pull`

<%= fetch_content(:optional_put_content_length) %>

{{#tip}}

We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the[blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

**Warning:** If you use this API to add a collaborator to a repository that's owned by an organization that hasn't had[improved organization permissions](https://github.com/blog/2020-improved-organization-permissions) enabled yet, you will get a`422` error response.

{{/tip}}

<%= headers 204 %>