APIs.io Engineering Platform Roles API

openapi: 3.0.0
info:
  version: "1.0.0"
  x-release: v4
  title: APIs.io Engineering Platform Amazon API Gateway 2014 11 13 Roles API
  description: <fullname>Amazon API Gateway</fullname> <p>Amazon API Gateway helps developers deliver robust, secure, and scalable mobile and web application back ends. API Gateway allows developers to securely connect mobile and web applications to APIs that run on AWS Lambda, Amazon EC2, or other publicly addressable web services that are hosted outside of AWS.</p>
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png
    backgroundColor: '#FFFFFF'
  termsOfService: https://aws.amazon.com/service-terms/
  contact:
    name: Mike Ralphson
    email: mike.ralphson@gmail.com
    url: https://github.com/mermade/aws2openapi
    x-twitter: PermittedSoc
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/
  x-providerName: amazonaws.com
  x-serviceName: apigateway
  x-origin:
  - contentType: application/json
    url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/apigateway-2015-07-09.normal.json
    converter:
      url: https://github.com/mermade/aws2openapi
    x-apisguru-driver: external
  x-apiClientRegistration:
    url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
  x-apisguru-categories:
  - cloud
  x-preferred: true
servers:
- url: http://apigateway.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Amazon API Gateway multi-region endpoint
- url: https://apigateway.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Amazon API Gateway multi-region endpoint
- url: http://apigateway.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
- url: https://apigateway.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
security:
- hmac: []
tags:
- name: Roles
  description: The **Roles** endpoints enable you to manage user roles. [Roles])(https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/) define user permissions within a Postman workspace.
paths:
  /collections/{collectionId}/roles:
    parameters:
    - $ref: '#/components/parameters/collectionId'
    get:
      summary: APIs.io Engineering Platform Get a collection's roles
      description: Gets information about all roles in a collection. The response returns the IDs of all users, teams, and groups with access to view or edit the collection.
      operationId: getCollectionRoles
      tags:
      - Roles
      responses:
        '200':
          $ref: '#/components/responses/getCollectionRoles'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/common403ErrorPermissions'
        '404':
          $ref: '#/components/responses/collection404ErrorInstanceNotFound'
        '500':
          $ref: '#/components/responses/common500ErrorInternalServer'
    patch:
      summary: APIs.io Engineering Platform Update a collection's roles
      description: 'Updates the roles of users, groups, or teams in a collection. On success, this returns an HTTP `204 No Content` response.


        **Note:**


        - Only users assigned the EDITOR [role](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#collection-roles) in the collection can use this endpoint.

        - This endpoint does not support the external [Partner or Guest roles](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#team-roles).

        '
      operationId: updateCollectionRoles
      tags:
      - Roles
      requestBody:
        $ref: '#/components/requestBodies/updateCollectionRoles'
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/collectionRoles400ErrorMissingProperty'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/common403ErrorPermissions'
        '404':
          $ref: '#/components/responses/collection404ErrorInstanceNotFound'
        '500':
          $ref: '#/components/responses/common500ErrorInternalServer'
  /workspaces-roles:
    get:
      summary: APIs.io Engineering Platform Get all roles
      description: 'Gets information about all roles in a workspace, based on the team''s [plan](https://www.postman.com/pricing/).

        '
      operationId: getAllWorkspaceRoles
      tags:
      - Roles
      responses:
        '200':
          $ref: '#/components/responses/getAllWorkspaceRoles'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/common403ErrorPermissions'
        '500':
          $ref: '#/components/responses/common500ErrorInternalServer'
  /workspaces/{workspaceId}/roles:
    parameters:
    - $ref: '#/components/parameters/workspaceId'
    patch:
      summary: APIs.io Engineering Platform Update user or user group roles
      description: 'Updates the roles of [users](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#team-roles) or [user groups](https://learning.postman.com/docs/collaborating-in-postman/user-groups/) in a workspace. To get a list of roles, use the `GET /workspace-roles` endpoint.


        **Note:**


        - To use SCIM IDs, include the `identifierType=scim` header when you call this endpoint. To get SCIM user IDs, include the `include=scim` query parameter when calling the GET `/workspaces/{workspaceId}` or GET `/workspaces` endpoints.

        - You cannot set roles for users in personal and partner workspaces.

        - This endpoint does not support the external [Partner or Guest roles](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#team-roles).

        - This endpoint is restricted to 50 operations per call.

        - The request body must contain one unique action per user or user group. For example, you cannot add and remove multiple roles for a user in the same request body.

        '
      operationId: updateWorkspaceRoles
      tags:
      - Roles
      requestBody:
        $ref: '#/components/requestBodies/updateWorkspaceRoles'
      responses:
        '200':
          $ref: '#/components/responses/updateWorkspaceRoles'
        '400':
          $ref: '#/components/responses/workspaceRoles400Error'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/common403ErrorPermissions'
        '404':
          $ref: '#/components/responses/resourceNotFound404Error'
        '422':
          $ref: '#/components/responses/workspaceRoles422UnsupportRoleError'
        '500':
          $ref: '#/components/responses/common500ErrorInternalServer'
      parameters:
      - $ref: '#/components/parameters/identifierType'
    get:
      summary: APIs.io Engineering Platform Get a workspace's roles
      description: 'Gets the roles of users and user groups in a workspace:

        - `Viewer` — Can view, fork, and export workspace resources.

        - `Editor` — Can create and edit workspace resources.

        - `Admin` — Can manage workspace details and members.

        '
      operationId: getWorkspaceRoles
      tags:
      - Roles
      responses:
        '200':
          $ref: '#/components/responses/getWorkspaceRoles'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/common403ErrorPermissions'
        '404':
          $ref: '#/components/responses/resourceNotFound404Error'
        '500':
          $ref: '#/components/responses/common500ErrorInternalServer'
      parameters:
      - $ref: '#/components/parameters/workspaceIncludeScimQuery'
components:
  parameters:
    workspaceIncludeScimQuery:
      name: include
      in: query
      description: 'Include the following information in the endpoint''s response:

        - `scim` — Return IDs as SCIM user and group IDs.

        '
      schema:
        type: string
        example: scim
        enum:
        - scim
    collectionId:
      name: collectionId
      in: path
      required: true
      description: The collection's ID.
      schema:
        type: string
        example: 12ece9e1-2abf-4edc-8e34-de66e74114d2
    workspaceId:
      name: workspaceId
      in: path
      required: true
      description: The workspace's ID.
      schema:
        $ref: '#/components/schemas/workspaceId'
    identifierType:
      name: identifierType
      in: header
      description: Use SCIM user IDs instead of Postman user IDs.
      schema:
        type: string
        example: scim
  responses:
    getCollectionRoles:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            description: Information about the collection's roles.
            properties:
              group:
                type: array
                description: A list of the collection's group roles.
                items:
                  type: object
                  description: Information about the group role.
                  properties:
                    role:
                      type: string
                      description: 'The role type:

                        - `VIEWER` — Can view, fork, and export collections.

                        - `EDITOR` — Can edit collections directly.

                        '
                      enum:
                      - VIEWER
                      - EDITOR
                      example: VIEWER
                    id:
                      type: number
                      description: The role's ID.
                      example: 123
              team:
                type: array
                description: A list of the collection's team roles.
                items:
                  type: object
                  description: Information about the team role.
                  properties:
                    role:
                      type: string
                      description: 'The role type:

                        - `VIEWER` — Can view, fork, and export collections.

                        - `EDITOR` — Can edit collections directly.

                        '
                      enum:
                      - VIEWER
                      - EDITOR
                      example: EDITOR
                    id:
                      type: number
                      description: The role's ID.
                      example: 1
              user:
                type: array
                description: A list of the collection's user roles.
                items:
                  type: object
                  description: Information about the user role.
                  properties:
                    role:
                      type: string
                      description: 'The role type:

                        - `VIEWER` — Can view, fork, and export collections.

                        - `EDITOR` — Can edit collections directly.

                        '
                      enum:
                      - VIEWER
                      - EDITOR
                      example: VIEWER
                    id:
                      type: number
                      description: The role's ID.
                      example: 12345678
          example:
            group:
            - role: VIEWER
              id: 123
            team:
            - role: EDITOR
              id: 1
            user:
            - role: VIEWER
              id: 12345678
            - role: EDITOR
              id: 87654321
    api401ErrorUnauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/unauthorized
              title:
                type: string
                description: A short summary of the problem.
                example: Unauthorized
              detail:
                type: string
                description: Information about the error.
                example: An API key must be provided in the request header or query string
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 401
              instance:
                type: string
                description: The URI reference that identifies the specific occurrence of the problem.
                example: /collections/12ece9e1-2abf-4edc-8e34-de66e74114d2/requests/%7B%7BrequestId%7D%7D
          example:
            type: https://api.postman.com/problems/unauthorized
            title: Unauthorized
            detail: An API key must be provided in the request header or query string
            status: 401
            instance: /collections/12ece9e1-2abf-4edc-8e34-de66e74114d2/requests/%7B%7BrequestId%7D%7D
    common403ErrorPermissions:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/forbidden
              title:
                type: string
                description: A short summary of the problem.
                example: Resource cannot be accessed
              detail:
                type: string
                description: Information about the error.
                example: Inadequate permissions. Resource access forbidden.
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 403
          example:
            type: https://api.postman.com/problems/forbidden
            title: Resource cannot be accessed
            detail: Inadequate permissions. Resource access forbidden.
            status: 403
    common500ErrorInternalServer:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/internal-server-error
              title:
                type: string
                description: A short summary of the problem.
                example: Internal Sever Error
              detail:
                type: string
                description: An explanation about the problem.
                example: Internal Sever Error
              status:
                type: integer
                format: http-status-code
                description: The HTTP status code generated by the origin server.
                example: 500
          example:
            type: https://api.postman.com/problems/internal-server-error
            title: Internal Server Error
            detail: Internal Server Error
            status: 500
    collection404ErrorInstanceNotFound:
      description: Instance Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  title:
                    type: string
                    description: A short summary of the problem.
                    example: We could not find the collection you are looking for
                  type:
                    type: string
                    description: The type of error.
                    example: instanceNotFoundError
          example:
            title: We could not find the collection you are looking for
            type: instanceNotFoundError
    collectionRoles400ErrorMissingProperty:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  type:
                    type: string
                    format: uri-reference
                    description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                    example: https://api.postman.com/problems/bad-request
                  title:
                    type: string
                    description: A short summary of the problem.
                    example: 'Missing properties: ''path'''
                  detail:
                    type: string
                    description: Information about the error.
                    example: 'PATCH request body for ''/collections/12ece9e1-2abf-4edc-8e34-de66e74114d2/roles/roles'' failed to validate schema. Location: /properties/roles/items/required'
                  status:
                    type: number
                    format: http-status-code
                    description: The error's HTTP status code.
                    example: 400
          example:
            type: https://api.postman.com/problems/bad-request
            title: 'Missing properties: ''path'''
            detail: 'PATCH request body for ''/collections/12ece9e1-2abf-4edc-8e34-de66e74114d2/roles/roles'' failed to validate schema. Location: /properties/roles/items/required'
            status: 400
    resourceNotFound404Error:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/not-found
              title:
                type: string
                description: A short summary of the problem.
                example: Resource not found
              detail:
                type: string
                description: Information about the error.
                example: ''
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 404
          example:
            type: https://api.postman.com/problems/not-found
            title: Resource not found
            detail: ''
            status: 404
    workspaceRoles400Error:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                description: The error type.
                example: invalidParamError
              title:
                type: string
                description: A short summary of the problem.
                example: body.roles[0] should have required property 'op'
              detail:
                type: string
                description: Information about the error.
                example: ''
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 400
          example:
            type: invalidParamError
            title: body.roles[0] should have required property 'op'
            detail: ''
            status: 400
    updateWorkspaceRoles:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              roles:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The role's ID.
                      example: '1'
                    user:
                      type: array
                      description: A list of user IDs assigned to the role.
                      items:
                        type: string
                        description: The user's ID or SCIM ID.
                        example: '12345678'
                    group:
                      type: array
                      description: A list of user group IDs assigned to the role.
                      items:
                        type: string
                        description: The user group's ID or SCIM ID.
                        example: 561631fq14ed41872a8eea4c8aa2b38cda9749812cc55c00
                    displayName:
                      type: string
                      description: The role's display name.
                      enum:
                      - Admin
                      - Viewer
                      - Editor
                      example: Viewer
          examples:
            Update User Role:
              $ref: '#/components/examples/userRoleUpdated'
            Update Role with SCIM ID:
              $ref: '#/components/examples/userRoleUpdatedSCIMId'
            Update Role and Group with SCIM IDs:
              $ref: '#/components/examples/userRoleGroupUpdatedSCIMId'
    unauthorizedError:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/unauthorized
              title:
                type: string
                description: A short summary of the problem.
                example: Unauthorized
              detail:
                type: string
                description: Information about the error.
                example: An API key must be provided in the request header or query string
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 401
          example:
            type: https://api.postman.com/problems/unauthorized
            title: Unauthorized
            detail: An API key must be provided in the request header or query string
            status: 401
    getWorkspaceRoles:
      description: Successful Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getWorkspaceRoles'
          examples:
            Successful Response:
              $ref: '#/components/examples/workspaceRoles'
            Return SCIM IDs:
              $ref: '#/components/examples/workspaceRolesScimIds'
    workspaceRoles422UnsupportRoleError:
      description: Partner and Personal Workspace Roles Unsupported
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                description: Information about the error.
                example: Roles are not supported for personal and partner workspaces.
              link:
                type: string
                description: The error type.
                example: https://api.postman.com/problems/unprocessable-entity
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 422
              title:
                type: string
                description: A short summary of the problem.
                example: Cannot process the request.
          example:
            detail: Roles are not supported for personal and partner workspaces.
            link: https://api.postman.com/problems/unprocessable-entity
            status: 422
            title: Cannot process the request.
    getAllWorkspaceRoles:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              roles:
                type: object
                description: Information about the workspace's [user roles](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#team-roles).
                properties:
                  user:
                    type: array
                    description: The list of user roles in the workspace.
                    items:
                      type: object
                      description: Information about the user role.
                      properties:
                        id:
                          type: string
                          description: The role's ID.
                          example: '1'
                        description:
                          type: string
                          description: The role's description.
                          example: Can manage people and all resources
                        displayName:
                          type: string
                          description: The role's display name.
                          example: Admin
                  usergroup:
                    type: array
                    description: Information about the workspace's [user group roles](https://learning.postman.com/docs/collaborating-in-postman/user-groups/).
                    items:
                      type: object
                      description: Information about the user group in the workspace.
                      properties:
                        id:
                          type: string
                          description: The role's ID.
                          example: '1'
                        description:
                          type: string
                          description: The role's description.
                          example: Can manage people and all resources
                        displayName:
                          type: string
                          description: The role's display name.
                          example: Admin
          example:
            roles:
              user:
              - id: '3'
                displayName: Admin
                description: Can manage workspace details and members.
              - id: '1'
                displayName: Viewer
                description: Can view, fork, and export workspace resources.
              - id: '2'
                displayName: Editor
                description: Can create and edit workspace resources.
              usergroup:
              - id: '3'
                displayName: Admin
                description: Can manage workspace details and members.
              - id: '1'
                displayName: Viewer
                description: Can view, fork, and export workspace resources.
              - id: '2'
                displayName: Editor
                description: Can create and edit workspace resources.
  requestBodies:
    updateWorkspaceRoles:
      content:
        application/json-patch+json:
          schema:
            type: object
            properties:
              roles:
                type: array
                items:
                  type: object
                  required:
                  - op
                  - path
                  - value
                  properties:
                    op:
                      type: string
                      description: The operation to perform on the path.
                      example: add
                    path:
                      type: string
                      description: The resource to perform the action on.
                      enum:
                      - /user
                      - /usergroup
                      example: /user
                    value:
                      type: array
                      items:
                        type: object
                        required:
                        - id
                        - role
                        description: Information about the updated user or user group role.
                        properties:
                          id:
                            type: string
                            description: The user or user group ID. To use SCIM IDs for users or groups, include the `identifierType=scim` header in the request.
                            example: '12345678'
                          role:
                            type: string
                            description: 'The workspace role''s ID:

                              - `1` — Viewer. Can view, fork, and export workspace resources.

                              - `2` — Editor. Can create and edit workspace resources.

                              - `3` — Admin. Can manage workspace details and members.

                              '
                            enum:
                            - '1'
                            - '2'
                            - '3'
                            example: '1'
          examples:
            Update User Role:
              $ref: '#/components/examples/updateUserRole'
            Update Role with SCIM ID:
              $ref: '#/components/examples/updateRoleSCIMId'
            Update Role and Group with SCIM IDs:
              $ref: '#/components/examples/updateRoleGroupSCIMId'
    updateCollectionRoles:
      content:
        application/json:
          schema:
            type: object
            required:
            - roles
            properties:
              roles:
                type: array
                items:
                  type: object
                  required:
                  - op
                  - path
                  - value
                  properties:
                    op:
                      type: string
                      description: The operation to perform on the path.
                      enum:
                      - update
                      example: update
                    path:
                      type: string
                      description: The resource to perform the action on.
                      enum:
                      - /user
                      - /group
                      - /team
                      example: /user
                    value:
                      type: array
                      items:
                        type: object
                        description: Information about

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apis-io-engineering-platform/refs/heads/main/openapi/engineering-platform-roles-api-openapi.yml