---
title: "Update Team Group Mappings"
url: "https://nov18-dev.movespot.fyi/apis/portal-management-v3-3/versions/209d0e93-97b5-4dd3-a5a4-172ba6d8a51e/operations/update-portal-team-group-mappings"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/portal-management-v3-3/versions/209d0e93-97b5-4dd3-a5a4-172ba6d8a51e.md

# Update Team Group Mappings

`PATCH` `/portals/{portalId}/identity-provider/team-group-mappings`

Operation ID: `update-portal-team-group-mappings`

**Pre-release Endpoint** This endpoint is currently in beta and is subject to change. Allows partial updates to the mappings between Konnect portal teams and Identity Provider (IdP) groups. The request body must be keyed on team ID. For a given team ID, the given group list is a complete replacement. To remove all mappings for a given team, provide an empty group list. Returns a 400 error if an IdP has not yet been configured, or if a team ID in the request body is not found or is not a UUID.

## Path parameters

- `portalId` (string, uuid, required) - ID of the portal.

## Request body

Content types: `application/json`

## Responses

- `200` - A paginated collection of mappings grouped by team ID.
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden

## OpenAPI definition

```yaml
openapi: 3.0.3
info:
  title: Portal Management V3
  version: 3.4.1
servers:
  - url: https://us.api.konghq.com/v3
    description: United-States Production region
  - url: https://eu.api.konghq.com/v3
    description: Europe Production region
  - url: https://au.api.konghq.com/v3
    description: Australia Production region
  - url: https://me.api.konghq.com/v3
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v3
    description: India Production region
  - url: https://sg.api.konghq.com/v3
    description: Singapore Production region
paths:
  /portals/{portalId}/identity-provider/team-group-mappings:
    parameters:
      - $ref: "#/components/parameters/PortalId"
    patch:
      operationId: update-portal-team-group-mappings
      summary: Update Team Group Mappings
      description: >-
        **Pre-release Endpoint**

        This endpoint is currently in beta and is subject to change.


        Allows partial updates to the mappings between Konnect portal teams and
        Identity Provider (IdP) groups. The request body must be keyed on team
        ID. For a given team ID, the given group list is a complete replacement.
        To remove all mappings for a given team, provide an empty group list.

        Returns a 400 error if an IdP has not yet been configured, or if a team
        ID in the request body is not found or is not a UUID.
      requestBody:
        $ref: "#/components/requestBodies/UpdatePortalTeamGroupMappings"
      responses:
        "200":
          $ref: "#/components/responses/PortalTeamGroupMappingCollection"
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/BadRequestError"
              examples:
                UpdateTeamGroupMappingsBadRequestExample1:
                  $ref: "#/components/examples/UpdateTeamGroupMappingsBadRequestExample1"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      tags:
        - Portal Auth Settings
security:
  - personalAccessToken: []
  - systemAccountAccessToken: []
components:
  parameters:
    PortalId:
      schema:
        type: string
        format: uuid
      name: portalId
      in: path
      required: true
      description: ID of the portal.
  requestBodies:
    UpdatePortalTeamGroupMappings:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PortalTeamGroupMappingsUpdateRequest"
          examples:
            Example 1:
              $ref: "#/components/examples/UpdatePortalTeamGroupMappingsExample1"
  responses:
    PortalTeamGroupMappingCollection:
      description: A paginated collection of mappings grouped by team ID.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PortalTeamGroupMappingResponse"
          examples:
            Example 1:
              $ref: "#/components/examples/PortalTeamGroupMappingCollectionExample1"
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/UnauthorizedError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/UnauthorizedExample"
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ForbiddenError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/ForbiddenExample"
  schemas:
    BadRequestError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          required:
            - invalid_parameters
          properties:
            invalid_parameters:
              $ref: "#/components/schemas/InvalidParameters"
    PortalTeamGroupMappingsUpdateRequest:
      description: A set of mappings to update from a team to their groups.
      type: object
      properties:
        data:
          description: The IdP groups to map to the given team.
          type: array
          items:
            type: object
            properties:
              team_id:
                type: string
                format: uuid
              groups:
                type: array
                items:
                  type: string
      example:
        data:
          - team_id: af91db4c-6e51-403e-a2bf-33d27ae50c0a
            groups:
              - Service Developer
      title: PortalTeamGroupMappingsUpdateRequest
    PortalTeamGroupMappingResponse:
      description: A paginated list of portal team group mappings.
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/PaginatedMeta"
        data:
          type: array
          items:
            $ref: "#/components/schemas/PortalTeamGroupMapping"
      example:
        meta:
          page:
            number: 1
            size: 10
            total: 2
        data:
          - team_id: 6801e673-cc10-498a-94cd-4271de07a0d3
            groups:
              - Tech Leads
              - API Engineers
          - team_id: 7301e673-cc10-498a-94cd-4271de07a0d3
            groups:
              - Managers
              - Directors
      title: PortalTeamGroupMappingResponse
    BaseError:
      description: standard error
      type: object
      properties:
        status:
          description: >
            The HTTP status code of the error. Useful when passing the response

            body to child properties in a frontend UI. Must be returned as an
            integer.
          type: integer
          readOnly: true
        title:
          description: |
            A short, human-readable summary of the problem. It should not
            change between occurences of a problem, except for localization.
            Should be provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
        type:
          description: The error type.
          type: string
          readOnly: true
        instance:
          description: |
            Used to return the correlation ID back to the user, in the format
            kong:trace:<correlation_id>. This helps us find the relevant logs
            when a customer reports an issue.
          type: string
          readOnly: true
        detail:
          description: >
            A human readable explanation specific to this occurence of the
            problem.

            This field may contain request/entity data to help the user
            understand

            what went wrong. Enclose variable values in square brackets. Should
            be

            provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
      required:
        - status
        - title
        - instance
        - detail
      title: Error
    InvalidParameters:
      description: invalid parameters
      type: array
      items:
        oneOf:
          - $ref: "#/components/schemas/InvalidParameterStandard"
          - $ref: "#/components/schemas/InvalidParameterMinimumLength"
          - $ref: "#/components/schemas/InvalidParameterMaximumLength"
          - $ref: "#/components/schemas/InvalidParameterChoiceItem"
          - $ref: "#/components/schemas/InvalidParameterDependentItem"
      minItems: 1
      nullable: false
      uniqueItems: true
    UnauthorizedError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 401
            title:
              example: Unauthorized
            type:
              example: https://httpstatuses.com/401
            instance:
              example: kong:trace:1234567890
            detail:
              example: Invalid credentials
    ForbiddenError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 403
            title:
              example: Forbidden
            type:
              example: https://httpstatuses.com/403
            instance:
              example: kong:trace:1234567890
            detail:
              example: Forbidden
    PaginatedMeta:
      description: returns the pagination information
      type: object
      properties:
        page:
          $ref: "#/components/schemas/PageMeta"
      required:
        - page
      title: PaginatedMeta
    PortalTeamGroupMapping:
      description: A map of portal teams to Identity Provider groups.
      type: object
      properties:
        team_id:
          description: The Konnect team ID.
          type: string
          format: uuid
          example: 6801e673-cc10-498a-94cd-4271de07a0d3
        groups:
          description: The IdP groups that are mapped to the specified team.
          type: array
          items:
            type: string
            example: API Engineers
          uniqueItems: true
      example:
        team_id: 6801e673-cc10-498a-94cd-4271de07a0d3
        groups:
          - Tech Leads
          - API Engineers
      title: PortalTeamGroupMapping
    InvalidParameterStandard:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          $ref: "#/components/schemas/InvalidRules"
        source:
          type: string
          example: body
        reason:
          type: string
          example: is a required field
          readOnly: true
      additionalProperties: false
      required:
        - field
        - reason
    InvalidParameterMinimumLength:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - min_length
            - min_digits
            - min_lowercase
            - min_uppercase
            - min_symbols
            - min_items
            - min
          nullable: false
          readOnly: true
        minimum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must have at least 8 characters
          readOnly: true
      additionalProperties: false
      required:
        - field
        - reason
        - rule
        - minimum
    InvalidParameterMaximumLength:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - max_length
            - max_items
            - max
          nullable: false
          readOnly: true
        maximum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must not have more than 8 characters
          readOnly: true
      additionalProperties: false
      required:
        - field
        - reason
        - rule
        - maximum
    InvalidParameterChoiceItem:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - enum
          nullable: false
          readOnly: true
        reason:
          type: string
          example: is a required field
          readOnly: true
        choices:
          type: array
          items: {}
          minItems: 1
          nullable: false
          readOnly: true
          uniqueItems: true
        source:
          type: string
          example: body
      additionalProperties: false
      required:
        - field
        - reason
        - rule
        - choices
    InvalidParameterDependentItem:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - dependent_fields
          nullable: true
          readOnly: true
        reason:
          type: string
          example: is a required field
          readOnly: true
        dependents:
          type: array
          items: {}
          nullable: true
          readOnly: true
          uniqueItems: true
        source:
          type: string
          example: body
      additionalProperties: false
      required:
        - field
        - rule
        - reason
        - dependents
    PageMeta:
      description: Contains pagination query parameters and the total number of
        objects returned.
      type: object
      properties:
        number:
          type: number
          example: 1
        size:
          type: number
          example: 10
        total:
          type: number
          example: 100
      required:
        - number
        - size
        - total
    InvalidRules:
      description: invalid parameters rules
      type: string
      enum:
        - required
        - is_array
        - is_base64
        - is_boolean
        - is_date_time
        - is_integer
        - is_null
        - is_number
        - is_object
        - is_string
        - is_uuid
        - is_fqdn
        - is_arn
        - unknown_property
        - missing_reference
        - is_label
        - matches_regex
        - invalid
        - is_supported_network_availability_zone_list
        - is_supported_network_cidr_block
        - is_supported_provider_region
        - type
      nullable: true
      readOnly: true
  examples:
    UpdateTeamGroupMappingsBadRequestExample1:
      value:
        status: 400
        title: Invalid Request
        instance: kong:trace:1433447772874964729
        detail: Invalid Parameters
        invalid_parameters:
          - field: data
            rule: is_array
            reason: '"data" must be an array'
            source: body
    UpdatePortalTeamGroupMappingsExample1:
      value:
        data:
          - team_id: af91db4c-6e51-403e-a2bf-33d27ae50c0a
            groups:
              - Service Developer
          - team_id: bc11db4c-6e51-403e-a2bf-33d27ae50c0a
            groups:
              - Service Owner
    PortalTeamGroupMappingCollectionExample1:
      value:
        meta:
          page:
            number: 1
            size: 10
            total: 2
        data:
          - team_id: 6801e673-cc10-498a-94cd-4271de07a0d3
            groups:
              - Tech Leads
              - API Engineers
          - team_id: 7301e673-cc10-498a-94cd-4271de07a0d3
            groups:
              - Managers
              - Directors
    UnauthorizedExample:
      value:
        status: 401
        title: Unauthorized
        instance: kong:trace:8347343766220159418
        detail: Unauthorized
    ForbiddenExample:
      value:
        status: 403
        title: Forbidden
        instance: kong:trace:2723154947768991354
        detail: You do not have permission to perform this action
  securitySchemes:
    personalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >
        The personal access token is meant to be used as an alternative to
        basic-auth when accessing Konnect via APIs.

        You can generate a Personal Access Token (PAT) from the [personal access
        token page](https://cloud.konghq.com/global/account/tokens/) in the
        Konnect dashboard.

        The PAT token must be passed in the header of a request, for example:

        `curl -X GET 'https://global.api.konghq.com/v2/users/' --header
        'Authorization: Bearer kpat_xgfT...'`
    systemAccountAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >
        The system account access token is meant for automations and
        integrations that are not directly associated with a human identity.

        You can generate a system account Access Token by creating a system
        account and then obtaining a system account access token for that
        account.

        The access token must be passed in the header of a request, for example:

        `curl -X GET 'https://global.api.konghq.com/v2/users/' --header
        'Authorization: Bearer spat_i2Ej...'`
```
