GitHub Memberships API

openapi: 3.2.0
info:
  title: Github Memberships API
  version: 1.1.4
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  description: 'Operations tagged Memberships across 2 of this provider''s published API definitions: github-organizations-openapi.yml, github-teams-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{protocol}://{hostname}/api/v3'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: HOSTNAME
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: http
tags:
- name: Memberships
paths:
  /orgs/{org}/teams/{team_slug}/memberships/{username}:
    get:
      summary: GitHub Get Team Membership for User
      description: 'Team members will include the members of child teams.


        To get a user''s membership with a team, the team must be visible to the authenticated user.


        **Note:** You can also specify a team by `org_id` and `team_id` using the route `GET /organizations/{org_id}/team/{team_id}/memberships/{username}`.


        **Note:**

        The response contains the `state` of the membership and the member''s `role`.


        The `role` for organization owners is set to `maintainer`. For more information about `maintainer` roles, see [Create a team](https://docs.github.com/enterprise-server@3.9/rest/teams/teams#create-a-team).'
      tags:
      - Memberships
      operationId: getTeamMembershipForUser
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/members#get-team-membership-for-a-user
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/team-slug'
      - $ref: '#/components/parameters/username'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/team-membership'
              examples:
                response-if-user-is-a-team-maintainer:
                  $ref: '#/components/examples/team-membership-response-if-user-is-a-team-maintainer'
        '404':
          description: if user has no team membership
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: teams
        subcategory: members
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      summary: GitHub Add or Update Team Membership for User
      description: 'Adds an organization member to a team. An authenticated organization owner or team maintainer can add organization members to a team.


        Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.


        **Note:** When you have team synchronization set up for a team with your organization''s identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team''s membership. If you have access to manage group membership in your IdP, you can manage GitHub Enterprise Server team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see "[Synchronizing teams between your identity provider and GitHub Enterprise Server](https://docs.github.com/enterprise-server@3.9/articles/synchronizing-teams-between-your-identity-provider-and-github/)."


        An organization owner can add someone who is not part of the team''s organization to a team. When an organization owner adds someone to a team who is not an organization member, this endpoint will send an invitation to the person via email. This newly-created membership will be in the "pending" state until the person accepts the invitation, at which point the membership will transition to the "active" state and the user will be added as a member of the team.


        If the user is already a member of the team, this endpoint will update the role of the team member''s role. To update the membership of a team member, the authenticated user must be an organization owner or a team maintainer.


        **Note:** You can also specify a team by `org_id` and `team_id` using the route `PUT /organizations/{org_id}/team/{team_id}/memberships/{username}`.'
      tags:
      - Memberships
      operationId: addOrUpdateTeamMembershipForUser
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/members#add-or-update-team-membership-for-a-user
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/team-slug'
      - $ref: '#/components/parameters/username'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  description: The role that this user should have in the team.
                  enum:
                  - member
                  - maintainer
                  default: member
            examples:
              default:
                summary: Add or update team membership for an organization member
                value:
                  role: maintainer
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/team-membership'
              examples:
                response-if-users-membership-with-team-is-now-pending:
                  $ref: '#/components/examples/team-membership-response-if-users-membership-with-team-is-now-pending'
        '403':
          description: Forbidden if team synchronization is set up
        '422':
          description: Unprocessable Entity if you attempt to add an organization to a team
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: teams
        subcategory: members
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Remove Team Membership for User
      description: 'To remove a membership between a user and a team, the authenticated user must have ''admin'' permissions to the team or be an owner of the organization that the team is associated with. Removing team membership does not delete the user, it just removes their membership from the team.


        Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.


        **Note:** When you have team synchronization set up for a team with your organization''s identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team''s membership. If you have access to manage group membership in your IdP, you can manage GitHub Enterprise Server team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see "[Synchronizing teams between your identity provider and GitHub Enterprise Server](https://docs.github.com/enterprise-server@3.9/articles/synchronizing-teams-between-your-identity-provider-and-github/)."


        **Note:** You can also specify a team by `org_id` and `team_id` using the route `DELETE /organizations/{org_id}/team/{team_id}/memberships/{username}`.'
      tags:
      - Memberships
      operationId: removeTeamMembershipForUser
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/members#remove-team-membership-for-a-user
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/team-slug'
      - $ref: '#/components/parameters/username'
      responses:
        '204':
          description: Response
        '403':
          description: Forbidden if team synchronization is set up
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: teams
        subcategory: members
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: '{protocol}://{hostname}/api/v3'
      variables:
        hostname:
          description: Self-hosted Enterprise Server hostname
          default: HOSTNAME
        protocol:
          description: Self-hosted Enterprise Server protocol
          default: http
  /teams/{team_id}/memberships/{username}:
    get:
      summary: GitHub Get Team Membership for User (legacy)
      description: '**Deprecation Notice:** This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new [Get team membership for a user](https://docs.github.com/enterprise-server@3.9/rest/teams/members#get-team-membership-for-a-user) endpoint.


        Team members will include the members of child teams.


        To get a user''s membership with a team, the team must be visible to the authenticated user.


        **Note:**

        The response contains the `state` of the membership and the member''s `role`.


        The `role` for organization owners is set to `maintainer`. For more information about `maintainer` roles, see [Create a team](https://docs.github.com/enterprise-server@3.9/rest/teams/teams#create-a-team).'
      tags:
      - Memberships
      operationId: getTeamMembershipForUserLegacy
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/members#get-team-membership-for-a-user-legacy
      parameters:
      - $ref: '#/components/parameters/team-id'
      - $ref: '#/components/parameters/username'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/team-membership'
              examples:
                response-if-user-is-a-team-maintainer:
                  $ref: '#/components/examples/team-membership-response-if-user-is-a-team-maintainer'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        removalDate: '2021-02-01'
        deprecationDate: '2020-01-21'
        category: teams
        subcategory: members
      deprecated: true
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      summary: GitHub Add or Update Team Membership for User (legacy)
      description: '**Deprecation Notice:** This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new [Add or update team membership for a user](https://docs.github.com/enterprise-server@3.9/rest/teams/members#add-or-update-team-membership-for-a-user) endpoint.


        Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.


        If the user is already a member of the team''s organization, this endpoint will add the user to the team. To add a membership between an organization member and a team, the authenticated user must be an organization owner or a team maintainer.


        **Note:** When you have team synchronization set up for a team with your organization''s identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team''s membership. If you have access to manage group membership in your IdP, you can manage GitHub Enterprise Server team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see "[Synchronizing teams between your identity provider and GitHub Enterprise Server](https://docs.github.com/enterprise-server@3.9/articles/synchronizing-teams-between-your-identity-provider-and-github/)."


        If the user is unaffiliated with the team''s organization, this endpoint will send an invitation to the user via email. This newly-created membership will be in the "pending" state until the user accepts the invitation, at which point the membership will transition to the "active" state and the user will be added as a member of the team. To add a membership between an unaffiliated user and a team, the authenticated user must be an organization owner.


        If the user is already a member of the team, this endpoint will update the role of the team member''s role. To update the membership of a team member, the authenticated user must be an organization owner or a team maintainer.'
      tags:
      - Memberships
      operationId: addOrUpdateTeamMembershipForUserLegacy
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/members#add-or-update-team-membership-for-a-user-legacy
      parameters:
      - $ref: '#/components/parameters/team-id'
      - $ref: '#/components/parameters/username'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  description: The role that this user should have in the team.
                  enum:
                  - member
                  - maintainer
                  default: member
            examples:
              default:
                summary: Assign the member role for a user in a team
                value:
                  role: member
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/team-membership'
              examples:
                response-if-users-membership-with-team-is-now-pending:
                  $ref: '#/components/examples/team-membership-response-if-users-membership-with-team-is-now-pending'
        '403':
          description: Forbidden if team synchronization is set up
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          description: Unprocessable Entity if you attempt to add an organization to a team
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        removalDate: '2021-02-01'
        deprecationDate: '2020-01-21'
        category: teams
        subcategory: members
      deprecated: true
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Remove Team Membership for User (legacy)
      description: '**Deprecation Notice:** This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new [Remove team membership for a user](https://docs.github.com/enterprise-server@3.9/rest/teams/members#remove-team-membership-for-a-user) endpoint.


        Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.


        To remove a membership between a user and a team, the authenticated user must have ''admin'' permissions to the team or be an owner of the organization that the team is associated with. Removing team membership does not delete the user, it just removes their membership from the team.


        **Note:** When you have team synchronization set up for a team with your organization''s identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team''s membership. If you have access to manage group membership in your IdP, you can manage GitHub Enterprise Server team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see "[Synchronizing teams between your identity provider and GitHub Enterprise Server](https://docs.github.com/enterprise-server@3.9/articles/synchronizing-teams-between-your-identity-provider-and-github/)."'
      tags:
      - Memberships
      operationId: removeTeamMembershipForUserLegacy
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/members#remove-team-membership-for-a-user-legacy
      parameters:
      - $ref: '#/components/parameters/team-id'
      - $ref: '#/components/parameters/username'
      responses:
        '204':
          description: Response
        '403':
          description: if team synchronization is set up
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        removalDate: '2021-02-01'
        deprecationDate: '2020-01-21'
        category: teams
        subcategory: members
      deprecated: true
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: '{protocol}://{hostname}/api/v3'
      variables:
        hostname:
          description: Self-hosted Enterprise Server hostname
          default: HOSTNAME
        protocol:
          description: Self-hosted Enterprise Server protocol
          default: http
components:
  parameters:
    team-slug:
      name: team_slug
      description: The slug of the team name.
      in: path
      required: true
      schema:
        type: string
    username:
      name: username
      description: The handle for the GitHub user account.
      in: path
      required: true
      schema:
        type: string
    org:
      name: org
      description: The organization name. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    team-id:
      name: team_id
      description: The unique identifier of the team.
      in: path
      required: true
      schema:
        type: integer
  examples:
    team-membership-response-if-users-membership-with-team-is-now-pending:
      summary: Response if user's membership with team is now pending
      value:
        url: https://api.github.com/teams/1/memberships/octocat
        role: member
        state: pending
    team-membership-response-if-user-is-a-team-maintainer:
      summary: Response if user is a team maintainer
      value:
        url: https://api.github.com/teams/1/memberships/octocat
        role: maintainer
        state: active
  schemas:
    team-membership:
      title: Team Membership
      description: Team Membership
      type: object
      properties:
        url:
          type: string
          format: uri
          example: https://api.github.com/repos/octocat/Hello-World
        role:
          description: The role of the user in the team.
          enum:
          - member
          - maintainer
          default: member
          example: member
          type: string
        state:
          description: The state of the user's membership in the team.
          type: string
          enum:
          - active
          - pending
          example: active
      required:
      - role
      - state
      - url
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        status:
          type: string
          example: open
  responses:
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer Token
      type: http
      scheme: Bearer
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/
x-refined-from:
- github-organizations-openapi.yml
- github-teams-openapi.yml