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
{{ message }}
This repository was archived by the owner on Nov 1, 2017. It is now read-only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
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]!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
`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`
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:
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
`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:
```
application/vnd.github.ironman-preview+json
```
**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`
#### Example
<%= json \
Expand All
@@ -84,23 +69,8 @@ Name | Type | Description
-----|------|--------------
`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:
```
application/vnd.github.ironman-preview+json
```
**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`
#### Example
Expand DownExpand Up
@@ -141,20 +111,7 @@ you will be able to list all members for the team.
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:
```
application/vnd.github.ironman-preview+json
```
{{/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`
### Response
Expand DownExpand Up
@@ -316,22 +273,7 @@ and a team, the authenticated user must be an organization owner.
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:
```
application/vnd.github.ironman-preview+json
```
**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`
### Response if user's membership with team is now active
Expand DownExpand Up
@@ -399,24 +341,11 @@ you will be able to list all repositories for the team.
### Alternative response with extra repository information
{{#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:
```
application/vnd.github.ironman-preview+json
```
{{/tip}}
You can also get information about the specified repository, including what
permissions the team grants on it, by passing the following custom
`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.
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:
```
application/vnd.github.ironman-preview+json
```
**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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
### Alternative response with extra repository information
{{#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:
`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`
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:
```
application/vnd.github.ironman-preview+json
```
**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}}
### Response
<%= headers 204 %>
Expand Down
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.