openapi: 3.2.0
info:
  title: Gloo Portal Server Teams API
  version: 1.0.0
  description: Review the following reference documentation for the Gloo portal server APIs, which has the endpoint specifications for managing user access to both the developer portal and resources exposed by the portal.
servers:
- url: http://portal.example.com/v1
tags:
- name: Teams
paths:
  /teams:
    get:
      description: Retrieve the teams of the current user
      operationId: ListTeams
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Team'
                type: array
          description: Successfully listed all teams
        '401':
          description: Unauthorized. The user's identity token is invalid
        '404':
          description: Teams not found
        '500':
          description: Unexpected error fetching teams
      security:
      - identityToken: []
      summary: Lists all teams
      tags:
      - Teams
    post:
      description: Create a new team associated with the user provided in the identity token
      operationId: CreateTeam
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamCreate'
        description: Team object that needs to be created
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          description: Successfully created the team
        '400':
          description: Bad request. The request body is invalid.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '404':
          description: User not found
        '409':
          description: User belongs to a team with the same name
        '500':
          description: Unexpected error creating the team
      security:
      - identityToken: []
      summary: Creates a team
      tags:
      - Teams
  /teams/{teamId}:
    delete:
      description: 'Delete a team.


        Prerequisite: All users and all apps associated with the team must be deleted before the team can be deleted.'
      operationId: DeleteTeam
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted the team
        '400':
          description: Bad request. The team has users or apps associated with it.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user does not have permission to delete the team
        '404':
          description: Team not found
        '500':
          description: Unexpected error deleting the team
      security:
      - identityToken: []
      summary: Deletes a team
      tags:
      - Teams
    get:
      description: Retrieve detailed information about a team by its ID
      operationId: GetTeamById
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          example: team-id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          description: Successfully retrieved team information
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user does not have permission to view the team.
        '404':
          description: Team not found
        '500':
          description: Unexpected error querying for team information
      security:
      - identityToken: []
      summary: Gets a team
      tags:
      - Teams
    put:
      description: Update an existing team
      operationId: UpdateTeam
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamUpdate'
        description: Team object that needs to be updated
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          description: Successfully updated team information
        '400':
          description: Bad request. The request body is invalid.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user does not have permission to update the team
        '404':
          description: Team not found
        '500':
          description: Unexpected error updating the team
      security:
      - identityToken: []
      summary: Updates a team
      tags:
      - Teams
  /teams/{teamId}/apps:
    get:
      description: Retrieve all team applications
      operationId: ListTeamApplications
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Application'
                type: array
          description: Successfully listed all team apps
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user does not have permission to view the team apps.
        '404':
          description: Team not found
        '500':
          description: Unexpected error fetching apps
      security:
      - identityToken: []
      summary: Lists all team apps
      tags:
      - Teams
    post:
      operationId: CreateTeamApplication
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreate'
        description: Application body
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
          description: Successfully created the team application
        '400':
          description: Bad request. The request body is invalid.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user does not have permission to create the application.
        '404':
          description: Team not found.
        '409':
          description: Application with the same name already exists in the team.
        '500':
          description: Unexpected error creating the application.
      security:
      - identityToken: []
      summary: Creates an application
      tags:
      - Teams
  /teams/{teamId}/members:
    get:
      description: Retrieve all team members
      operationId: ListTeamMembers
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/User'
                type: array
          description: List of team users
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '404':
          description: Team not found.
        '500':
          description: Unexpected error fetching team members.
      security:
      - identityToken: []
      summary: List of team users
      tags:
      - Teams
    post:
      description: 'Assign a user as a member to the team. If the user doesn''t exist within the system, an account will be automatically created and assigned.

        In order for this change to take effect, the client-side application has to send a `PUT` request to the `/me` endpoint with the user''s `id_token`, after they login.'
      operationId: AddTeamMember
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  description: Unique email of the user to add
                  type: string
              type: object
        description: User object that needs to be added to the team
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successfully added the user to the team
        '400':
          description: Bad request. The request body is invalid.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user does not have permission to add the member to the team.
        '404':
          description: Team not found or User not found.
        '500':
          description: Unexpected error adding member to the team.
      security:
      - identityToken: []
      summary: Adds a member to a team
      tags:
      - Teams
  /teams/{teamId}/members/{userId}:
    delete:
      description: 'Remove user from the team. The user will lose access to the team and its apps.

        However, if he has access to the app credentials he can still use those.'
      operationId: RemoveTeamMember
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          example: team-id
          type: string
      - description: Unique identifier of the user to remove
        in: path
        name: userId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully removed the user from the team
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user does not have permission to remove the member from the team.
        '404':
          description: Team not found or User not found in the team.
        '500':
          description: Unexpected error removing member from the team.
      security:
      - identityToken: []
      summary: Removes a member from a team
      tags:
      - Teams
components:
  schemas:
    BaseEntity:
      properties:
        createdAt:
          example: '2021-08-25T20:00:00Z'
          format: date-time
          readOnly: true
          type: string
        deletedAt:
          example: '2021-08-25T20:00:00Z'
          format: date-time
          readOnly: true
          type: string
        id:
          example: uuid
          readOnly: true
          type: string
        updatedAt:
          example: '2021-08-25T20:00:00Z'
          format: date-time
          readOnly: true
          type: string
    Team:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - $ref: '#/components/schemas/TeamCreate'
    TeamCreate:
      description: Create a new team
      properties:
        description:
          example: team description
          type: string
        name:
          example: ACME Team
          type: string
      required:
      - name
    User:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          email:
            example: johndoe@email.com
            type: string
          isAdmin:
            example: false
            type: boolean
          name:
            example: John Doe
            type: string
          synced:
            example: true
            type: boolean
          username:
            example: johndoe
            type: string
        required:
        - email
        type: object
    RateLimit:
      properties:
        requestsPerUnit:
          example: 5
          type: string
        unit:
          enum:
          - SECOND
          - MINUTE
          - HOUR
          - DAY
          - MONTH
          - YEAR
          example: SECOND
          type: string
    Application:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          description:
            example: app description
            type: string
          metadata:
            $ref: '#/components/schemas/ApplicationMetadata'
          name:
            example: app
            type: string
          teamId:
            example: 2frepq0mjp841i3jfd030dhtmn
            readOnly: true
            type: string
        type: object
    TeamUpdate:
      allOf:
      - $ref: '#/components/schemas/TeamCreate'
    ApplicationMetadata:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          customMetadata:
            example:
              key: value
            type: object
          rateLimit:
            $ref: '#/components/schemas/RateLimit'
        type: object
    ApplicationCreate:
      description: Create
      properties:
        description:
          example: app description
          type: string
        name:
          example: app
          type: string
      required:
      - name
  securitySchemes:
    identityToken:
      description: id token cookie from the identity provider used to authenticate the user
      in: cookie
      name: id_token
      type: apiKey