APIs.io Engineering Platform Roles API

openapi: 3.2.0
info:
  title: APIs.io Engineering Platform Postman Roles API
  description: "The Postman API enables you to programmatically access data stored in your Postman account.\n\n> Certain endpoints may be unavailable depending on your region and/or Postman plan.\n\nFor a comprehensive set of examples of requests and responses, see the [**Postman API** collection](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a).\n\n## Getting started\n\nYou can get started with the Postman API by creating a copy of this definition in your workspace.\n\n### EU users\n\nFor users in the EU with [**Enterprise** plans](https://www.postman.com/pricing/), the Postman API uses the `http://api.eu.postman.com` subdomain. This is available in the definition's list of servers. You can change this by selecting the `http://api.eu.postman.com` subdomain in the **Server** dropdown list below.\n\n## About the Postman API\n\n- You must use a valid API Key to send requests to the API endpoints.\n- The API has [rate and usage limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/).\n- The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP `301` redirect to the corresponding HTTPS resources.\n- The API returns requests responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key.\n- The request method (verb) determines the nature of action you intend to perform. A request made using the `GET` method implies that you want to fetch something from Postman. The `POST` method implies you want to save something new to Postman.\n- For all requests, API calls respond with their corresponding [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). In the Postman client, the status code also provides help text that details the possible meaning of the response code.\n- When calling the API Builder endpoints, you must send an `Accept` header with the `application/vnd.api.v10+json` value.\n\n### IDs and UIDs\n\nAll items in Postman, such as collections, workspaces, and APIs, have IDs and UIDs:\n\n- An ID is the unique ID assigned to a Postman item. For example, `ec29121c-5203-409f-9e84-e83ffc10f226`.\n- The UID is the **full** ID of a Postman item. This value is the item's unique ID concatenated with the user ID. For example, in the `12345678-ec29121c-5203-409f-9e84-e83ffc10f226` UID:\n    - `12345678` is the user's ID.\n    - `ec29121c-5203-409f-9e84-e83ffc10f226` is the item's ID.\n\n### Enum values\n\nAny documented enum values should be considered partial lists and may change over time.\n\n### 403 response for unavailable features\n\nDepending on your region and/or Postman [plan](https://www.postman.com/pricing/), some endpoints will return an HTTP `403 Forbidden` response with the \"This feature isn't available in your region.\" detail.\n\n### 503 response\n\nAn HTTP `503 Service Unavailable` response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes.\n\nIf the outage persists or you receive any other form of an HTTP `5XX` error, [contact support](https://support.postman.com/hc/en-us/requests/new/).\n\n## Authentication\n\nPostman uses API keys for authentication. The API key tells the API server that the request came from you. Everything that you have access to in Postman is accessible with your API key. You can [generate](https://learning.postman.com/docs/developer/postman-api/authentication/#generate-a-postman-api-key) a Postman API key in the [**API keys**](https://postman.postman.co/settings/me/api-keys) section of your Postman account settings.\n\nYou must include an API key in each request to the Postman API with the `X-API-Key` request header. In Postman, you can store your API key as a [vault secret](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/) or an [environment variable](https://www.getpostman.com/docs/environments). The Postman API [collection](https://www.getpostman.com/docs/collections) will use it to make API calls.\n\n### SCIM authentication\n\nWhile all other endpoints in this collection require a Postman API key, the SCIM endpoints require a [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key).\n\n### Authentication error response\n\nIf an API key is missing, malformed, or invalid, you will receive an HTTP `401 Unauthorized` response code.\n\n## Rate and usage limits\n\nAPI access [rate limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/) apply at a per-user basis in unit time. The limit is **300 requests per minute**. Postman Monitors, the GET `/collections`, and the GET `/workspaces` endpoint have a rate limit of **10 calls in 10 seconds**. Depending on your [plan](https://www.postman.com/pricing/), you may also have [usage limits](https://learning.postman.com/docs/billing/resource-usage/).\n\nWhen you reach your rate or usage limits, the API returns the following HTTP `429 Too Many Requests` status code with one of the following error responses:\n\n- `rateLimited` — Rate limits reached. The response returns the time after which you can resume calls to the Postman API.\n- `serviceLimitExhausted` — Postman API service limits reached. You will need to contact your Postman Team Admin for assistance.\n\n## Support\n\nFor help regarding accessing the Postman API, you can:\n\n- Visit [Postman Support](https://support.postman.com/hc/en-us) or our [Community and Support](https://www.postman.com/community/) sites.\n- Reach out to the [Postman community](https://community.postman.com/).\n- Submit a help request to [Postman support](https://support.postman.com/hc/en-us/requests/new/).\n\n## Policies\n\n- [Postman Terms of Service](http://www.postman.com/legal/terms/)\n- [Postman Privacy Policy](https://www.postman.com/legal/privacy-policy/)\n"
  version: '1.0'
  termsOfService: https://www.postman.com/legal/terms/
  contact:
    name: Postman Support
    email: help@postman.com
    url: https://www.postman.com/community/
servers:
- url: https://api.getpostman.com
- url: https://api.eu.postman.com
security:
- PostmanApiKey: []
- scimApiKey: []
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:
  examples:
    userRoleUpdated:
      value:
        roles:
        - id: '1'
          displayName: Viewer
          user:
          - '12345678'
          group:
          - '123'
        - id: '2'
          displayName: Editor
          user:
          - '87654321'
          group:
          - '123'
        - id: '3'
          displayName: Admin
          user:
          - '13428756'
          group:
          - '132'
    userRoleUpdatedSCIMId:
      value:
        roles:
        - id: '1'
          displayName: Viewer
          user:
          - 405775fe15ed41872a8eea4c8aa2b38cda9749812cc55c99
    updateUserRole:
      value:
        roles:
        - op: add
          path: /user
          value:
          - id: '12345678'
            role: '1'
          - id: '87654321'
            role: '2'
        - op: remove
          path: /user
          value:
          - id: '87612345'
            role: '1'
        - op: add
          path: /usergroup
          value:
          - id: '123'
            role: '2'
        - op: remove
          path: /usergroup
          value:
          - id: '312'
            role: '3'
    workspaceRolesScimIds:
      value:
        roles:
        - id: '3'
          displayName: Admin
          user:
          - 405775fe15ed41872a8eea4c8aa2b38cda9749812cc55c99
          group:
          - 561631fq14ed41872a8eea4c8aa2b38cda9749812cc55c00
    workspaceRoles:
      value:
        roles:
        - id: '3'
          displayName: Admin
          user:
          - '12345678'
          group:
          - '123'
    userRoleGroupUpdatedSCIMId:
      value:
        roles:
        - id: '3'
          displayName: Admin
          user:
          - e982929dadd02cf627e8c111925fc37a93dbc86f510840db
          group:
          - 561631fq14ed41872a8eea4c8aa2b38cda9749812cc55c00
    updateRoleSCIMId:
      value:
        roles:
        - op: add
          path: /user
          value:
          - id: 405775fe15ed41872a8eea4c8aa2b38cda9749812cc55c99
            role: '1'
    updateRoleGroupSCIMId:
      value:
        roles:
        - op: add
          path: /user
          value:
          - id: 405775fe15ed41872a8eea4c8aa2b38cda9749812cc55c99
            role: '3'
        - op: add
          path: /usergroup
          value:
          - id: 561631fq14ed41872a8eea4c8aa2b38cda9749812cc55c00
            role: '3'
  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
    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
    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
    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
    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
    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
    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
    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.
    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
    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'
    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'
    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 work

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