openapi: 3.0.1
info:
  contact:
    email: support@instana.com
    name: © Instana
    url: http://instana.com
  termsOfService: https://www.instana.com/terms-of-use/
  title: Instana REST API documentation Groups API
  version: 1.307.1417
  x-ibm-ahub-try: true
  x-logo:
    altText: instana logo
    backgroundColor: '#FAFBFC'
    url: header-logo.svg
  description: "Searching for answers and best pratices? Check our [IBM Instana Community](https://community.ibm.com/community/user/aiops/communities/community-home?CommunityKey=58f324a3-3104-41be-9510-5b7c413cc48f).\n\n<div style=\"background-color:#e6f0ff; padding: 12px; border-left: 6px solid #0052cc; font-size: 14px; display: flex; align-items: center;\">\n  <img src=\"https://img.icons8.com/ios-filled/50/0052cc/info.png\" width=\"18\" height=\"18\" style=\"margin-right: 8px;\" alt=\"info icon\"/>\n  <span>\n    <b>Our API documentation is moving to</b> \n    <a href=\"https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Introduction\" target=\"_blank\">API Hub</a>\n\t — please update your bookmarks now, as the current site will be deprecated after Release-306.\n  </span>\n</div>\n\n## Overview\nThe Instana REST API provides programmatic access to the Instana platform. It can be used to retrieve data available through the Instana UI Dashboard -- metrics, events, traces, etc -- and also to automate configuration tasks such as user management.\n\n### Navigating the API documentation\nThe API endpoints are grouped by product area and functionality. This generally maps to how our UI Dashboard is organized, hopefully making it easier to locate which endpoints you'd use to fetch the data you see visualized in our UI. The [UI sections](https://www.ibm.com/docs/en/instana-observability/current?topic=working-user-interface#navigation-menu) include:\n- Websites & Mobile Apps\n- Applications\n- Infrastructure\n- Synthetic Monitoring\n- Events\n- Automation\n- Service Levels\n- Settings\n- etc\n\n### Rate Limiting\nA rate limit is applied to API usage. Up to 5,000 calls per hour can be made. How many remaining calls can be made and when this call limit resets, can inspected via three headers that are part of the responses of the API server.\n\n- **X-RateLimit-Limit:** Shows the maximum number of calls that may be executed per hour.\n- **X-RateLimit-Remaining:** How many calls may still be executed within the current hour.\n- **X-RateLimit-Reset:** Time when the remaining calls will be reset to the limit. For compatibility reasons with other rate limited APIs, this date is not the date in milliseconds, but instead in seconds since 1970-01-01T00:00:00+00:00.\n\n### Further Reading\nWe provide additional documentation for our REST API in our [product documentation](https://www.ibm.com/docs/en/instana-observability/current?topic=apis-web-rest-api). Here you'll also find some common queries for retrieving data and configuring Instana.\n\n## Getting Started with the REST API\n\n### API base URL\nThe base URL for an specific instance of Instana can be determined using the tenant and unit information.\n- `base`: This is the base URL of a tenant unit, e.g. `https://test-example.instana.io`. This is the same URL that is used to access the Instana user interface.\n- `apiToken`: Requests against the Instana API require valid API tokens. An initial API token can be generated via the Instana user interface. Any additional API tokens can be generated via the API itself.\n\n### Curl Example\nHere is an Example to use the REST API with Curl. First lets get all the available metrics with possible aggregations with a GET call.\n\n```bash\ncurl --request GET \\\n  --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n  --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n\nNext we can get every call grouped by the endpoint name that has an error count greater then zero. As a metric we could get the mean error rate for example.\n\n```bash\ncurl --request POST \\\n  --url https://test-instana.instana.io/api/application-monitoring/analyze/call-groups \\\n  --header 'authorization: apiToken xxxxxxxxxxxxxxxx' \\\n  --header 'content-type: application/json' \\\n  --data '{\n  \"group\":{\n      \"groupbyTag\":\"endpoint.name\"\n  },\n  \"tagFilters\":[\n  \t{\n  \t\t\"name\":\"call.error.count\",\n  \t\t\"value\":\"0\",\n  \t\t\"operator\":\"GREATER_THAN\"\n  \t}\n  ],\n  \"metrics\":[\n  \t{\n  \t\t\"metric\":\"errors\",\n  \t\t\"aggregation\":\"MEAN\"\n  \t}\n  ]\n  }'\n```\n\n### Generating REST API clients\n\nThe API is specified using the [OpenAPI v3](https://github.com/OAI/OpenAPI-Specification) (previously known as Swagger) format.\nYou can download the current specification at our [GitHub API documentation](https://instana.github.io/openapi/openapi.yaml).\n\nOpenAPI tries to solve the issue of ever-evolving APIs and clients lagging behind. Please make sure that you always use the latest version of the generator, as a number of improvements are regularly made.\nTo generate a client library for your language, you can use the [OpenAPI client generators](https://github.com/OpenAPITools/openapi-generator).\n\n#### Go\nFor example, to generate a client library for Go to interact with our backend, you can use the following script; mind replacing the values of the `UNIT_NAME` and `TENANT_NAME` environment variables using those for your tenant unit:\n\n```bash\n#!/bin/bash\n\n### This script assumes you have the `java` and `wget` commands on the path\n\nexport UNIT_NAME='myunit' # for example: prod\nexport TENANT_NAME='mytenant' # for example: awesomecompany\n\n//Download the generator to your current working directory:\nwget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.3.1/openapi-generator-cli-4.3.1.jar -O openapi-generator-cli.jar --server-variables \"tenant=${TENANT_NAME},unit=${UNIT_NAME}\"\n\n//generate a client library that you can vendor into your repository\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g go \\\n    -o pkg/instana/openapi \\\n    --skip-validate-spec\n\n//(optional) format the Go code according to the Go code standard\ngofmt -s -w pkg/instana/openapi\n```\n\nThe generated clients contain comprehensive READMEs, and you can start right away using the client from the example above:\n\n```go\nimport instana \"./pkg/instana/openapi\"\n\n// readTags will read all available application monitoring tags along with their type and category\nfunc readTags() {\n\tconfiguration := instana.NewConfiguration()\n\tconfiguration.Host = \"tenant-unit.instana.io\"\n\tconfiguration.BasePath = \"https://tenant-unit.instana.io\"\n\n\tclient := instana.NewAPIClient(configuration)\n\tauth := context.WithValue(context.Background(), instana.ContextAPIKey, instana.APIKey{\n\t\tKey:    apiKey,\n\t\tPrefix: \"apiToken\",\n\t})\n\n\ttags, _, err := client.ApplicationCatalogApi.GetApplicationTagCatalog(auth)\n\tif err != nil {\n\t\tfmt.Fatalf(\"Error calling the API, aborting.\")\n\t}\n\n\tfor _, tag := range tags {\n\t\tfmt.Printf(\"%s (%s): %s\\n\", tag.Category, tag.Type, tag.Name)\n\t}\n}\n```\n\n#### Java\nFollow the instructions provided in the official documentation from [OpenAPI Tools](https://github.com/OpenAPITools) to download the [openapi-generator-cli.jar](https://github.com/OpenAPITools/openapi-generator?tab=readme-ov-file#13---download-jar).\n\nDepending on your environment, use one of the following java http client implementations which will create a valid client for our OpenAPI specification:\n```\n//Nativ Java HTTP Client\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec  -p dateLibrary=java8 --library native\n\n//Spring WebClient\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec  -p dateLibrary=java8,hideGenerationTimestamp=true --library webclient\n\n//Spring RestTemplate\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec  -p dateLibrary=java8,hideGenerationTimestamp=true --library resttemplate\n\n```\n"
servers:
- description: Instana Backend
  url: https://{unit}-{tenant}.instana.io
  variables:
    tenant:
      default: tenant
      description: Customer tenant unit
    unit:
      default: unit
      description: Customer tenant name
- description: Instana Self-Hosted Backend
  url: https://{domain}
  variables:
    domain:
      default: example.com
      description: Customer Self-Hosted domain
tags:
- name: Groups
  description: 'Groups are used to permit individual users to perform specific actions and get visibility to an access scope. Each user can be assigned to multiple groups, every one coming with its associated permissions. In addition a group sets the access scope and you can configure the visible areas for the group members.


    When you are a member of multiple groups, your permissions have an additive effect.


    Granting access to certain entities within Instana (e.g. Applications, Kubernetes Clusters etc.) is done through a corresponding entry in the `permissionSet` payload.

    '
paths:
  /api/settings/rbac/groups:
    get:
      operationId: getGroups
      responses:
        '200':
          content:
            application/json:
              example:
              - id: groupId1
                name: group1
                members:
                - userId: userId1
                  email: username1@example.com
                - userId: userId2
                  email: username2@example.com
              - id: groupId2
                name: group2
                members:
                - userId: userId1
                  email: username1@example.com
                - userId: userId3
                  email: username3@example.com
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiGroup'
          description: OK
        '404':
          description: No groups found
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Get groups
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: "Retrieve the list of all groups on the tenant together with the `Permission Set` for the tenant unit.\n\nThe `Permission Set` object contains a set of permissions applied to the group.\n\nIn case `permissions` include the entry e.g. `LIMITED_APPLICATIONS_SCOPE`, this group will have limited access to application area.\n\nThe areas are included inside the `permissionSet`.\n\nThe scopeRoleId is a fixed value for each area type:\n\n| Area                    | value         |\n| ----------------------- | ------------- |\n| applicationIds          | -100          |\n| kubernetesClusterUUIDs  | -200          |\n| kubernetesNamespaceUIDs | -300          |\n| websiteIds              | -400          |\n| mobileAppIds            | -500          |\n| infraDfqFilter          | -600          |\n\nFor example:\n\n```\n[\n    {\n        \"id\": \"7hwdhtt7TU2CJDgYXgwwww\",\n        \"name\": \"Scoped Group\",\n        \"members\": [\n            {\n                \"userId\": \"61892cfdfcffab03016b2950\",\n                \"email\": \"jhon@example.com\"\n            }\n        ],\n        \"permissionSet\": {\n        \"permissions\": [\n            \"CAN_VIEW_LOGS\",\n            \"CAN_VIEW_TRACE_DETAILS\",\n            \"CAN_EDIT_ALL_ACCESSIBLE_CUSTOM_DASHBOARDS\",\n            \"ACCESS_APPLICATIONS\",\n            \"LIMITED_APPLICATIONS_SCOPE\",            \n            \"ACCESS_KUBERNETES\",\n            \"LIMITED_KUBERNETES_SCOPE\",\n            \"ACCESS_INFRASTRUCTURE_APPS\",\n            \"LIMITED_INFRASTRUCTURE_SCOPE\",\n            \"LIMITED_WEBSITES_SCOPE\",\n            \n        ],\n        \"applicationIds\": [\n            {\n            \"scopeId\": \"1qvWgVfLTNqi9gGTcCaNUw\",\n            \"scopeRoleId\": \"-100\"\n            }\n        ],\n        \"kubernetesClusterUUIDs\": [\n            {\n            \"scopeId\": \"induced\",\n            \"scopeRoleId\": \"-200\"\n            }\n        ],\n        \"kubernetesNamespaceUIDs\": [],\n        \"websiteIds\": [],\n        \"mobileAppIds\": [],\n        \"infraDfqFilter\": {\n            \"scopeId\": \"production\",\n            \"scopeRoleId\": \"-600\"\n        }\n    }\n]\n```\nIn this case `Scoped Group` has no access to websites due to having `LIMITED_WEBSITES_SCOPE` but not `ACCESS_WEBSITES`.\n\nAlso due to having `LIMITED_APPLICATIONS_SCOPE`, the only visible application is the one with this id: `1qvWgVfLTNqi9gGTcCaNUw`.\n\nSame applies to `kubernetesClusterUUIDs`, `kubernetesNamespaceUIDs` and `infraDfqFilter`, with the only difference is that `infraDfqFilter`\nuses a filter \"production\" instead of an id."
    post:
      operationId: createGroup
      requestBody:
        content:
          application/json:
            example:
              name: group name
              members:
              - userId: userId
                email: username@example.com
              permissionSet:
                permissions:
                - CAN_VIEW_LOGS
                applicationIds:
                - scopeId: scopeId1
                  scopeRoleId: '-102'
                kubernetesClusterUUIDs: []
                kubernetesNamespaceUIDs: []
                websiteIds: []
                mobileAppIds: []
                syntheticTestIds:
                - scopeId: scopeId10
                  scopeRoleId: '-1'
                restrictedApplicationFilter:
                  label: group name
                  tagFilterExpression:
                    type: TAG_FILTER
                    name: service.name
                    stringValue: acceptor
                    numberValue: null
                    booleanValue: null
                    key: null
                    value: acceptor
                    operator: EQUALS
                    entity: DESTINATION
                  scope: INCLUDE_NO_DOWNSTREAM
                infraDfqFilter:
                  scopeId: ''
                  scopeRoleId: '-1'
                actionFilter:
                  scopeId: ''
                  scopeRoleId: '-1'
            schema:
              $ref: '#/components/schemas/ApiCreateGroup'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                name: group name
                members:
                - userId: userId
                  email: username@example.com
                permissionSet:
                  permissions:
                  - CAN_VIEW_LOGS
                  applicationIds:
                  - scopeId: scopeId1
                    scopeRoleId: '-102'
                  kubernetesClusterUUIDs: []
                  kubernetesNamespaceUIDs: []
                  websiteIds: []
                  mobileAppIds: []
                  syntheticTestIds:
                  - scopeId: scopeId10
                    scopeRoleId: '-1'
                  restrictedApplicationFilter:
                    label: group name
                    tagFilterExpression:
                      type: TAG_FILTER
                      name: service.name
                      stringValue: acceptor
                      numberValue: null
                      booleanValue: null
                      key: null
                      value: acceptor
                      operator: EQUALS
                      entity: DESTINATION
                    scope: INCLUDE_NO_DOWNSTREAM
                  infraDfqFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
                  actionFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
              schema:
                $ref: '#/components/schemas/ApiGroup'
          description: OK
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Create group
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: 'Creates a group on the tenant. Each group entry also needs a `Permission Set` per unit.


        The `Permission Set` object contains a set of permissions applied to the group.


        In case `permissions` include the entry e.g. `LIMITED_APPLICATIONS_SCOPE`, this group will have limited access to application area.


        Possible access permissions values are:


        - `ACCESS_APPLICATIONS`

        - `ACCESS_INFRASTRUCTURE`

        - `ACCESS_KUBERNETES`

        - `ACCESS_MOBILE_APPS`

        - `ACCESS_WEBSITES`

        - `LIMITED_APPLICATIONS_SCOPE`

        - `LIMITED_INFRASTRUCTURE_SCOPE`

        - `LIMITED_KUBERNETES_SCOPE`

        - `LIMITED_MOBILE_APPS_SCOPE`

        - `LIMITED_WEBSITES_SCOPE`


        The `id` value for the group is ignored, a new id is generated.


        The `scopeRoleId` is ignored, the id corresponding to the area is used.


        The `scopeId` is the id for the corresponding resource.'
  /api/settings/rbac/groups/delete:
    put:
      description: 'Delete multiple groups

        For more information on groups please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#groups.'
      operationId: deleteGroups
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              uniqueItems: true
        required: true
      responses:
        default:
          content:
            application/json: {}
          description: default response
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Delete groups
      tags:
      - Groups
      x-ibm-ahub-byok: true
  /api/settings/rbac/groups/user/{email}:
    get:
      operationId: getGroupsByUser
      parameters:
      - description: Email of the user for retrieval
        example: username@example.com
        in: path
        name: email
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              example:
              - id: groupId
                name: group name
                members:
                - userId: userId
                  email: username@example.com
                permissionSet:
                  permissions:
                  - CAN_VIEW_LOGS
                  - LIMITED_APPLICATIONS_SCOPE
                  - ACCESS_APPLICATIONS
                  - CAN_VIEW_TRACE_DETAILS
                  applicationIds:
                  - scopeId: scopeId1
                    scopeRoleId: '-102'
                  kubernetesClusterUUIDs: []
                  kubernetesNamespaceUIDs: []
                  websiteIds: []
                  mobileAppIds: []
                  syntheticTestIds: []
                  restrictedApplicationFilter:
                    label: filter name
                    tagFilterExpression:
                      type: TAG_FILTER
                      name: service.name
                      stringValue: acceptor
                      numberValue: null
                      booleanValue: null
                      key: null
                      value: acceptor
                      operator: EQUALS
                      entity: DESTINATION
                    scope: INCLUDE_NO_DOWNSTREAM
                  infraDfqFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
                  actionFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiGroup'
          description: OK
        '404':
          description: No groups found
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Get groups of a single user
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: Returns a list of all groups a user belongs to. This includes data from these groups, the `members`, the `name` and the `Permission set`.
  /api/settings/rbac/groups/{groupId}/permissions:
    put:
      operationId: addPermissionsOnGroup
      parameters:
      - description: Id of the group to add permissions
        example: groupId
        in: path
        name: groupId
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            example:
            - CAN_VIEW_SYNTHETIC_TESTS
            - CAN_VIEW_SYNTHETIC_LOCATIONS
            - CAN_CONFIGURE_AUTOMATION_ACTIONS
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                id: groupId
                name: group name
                members:
                - userId: userId1
                  email: username1@example.com
                permissionSet:
                  permissions:
                  - CAN_VIEW_LOGS
                  - CAN_VIEW_SYNTHETIC_TESTS
                  - CAN_VIEW_SYNTHETIC_LOCATIONS
                  - CAN_CONFIGURE_AUTOMATION_ACTIONS
                  applicationIds: []
                  kubernetesClusterUUIDs: []
                  kubernetesNamespaceUIDs: []
                  websiteIds: []
                  mobileAppIds: []
                  syntheticTestIds: []
                  infraDfqFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
                  actionFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
              schema:
                $ref: '#/components/schemas/ApiGroup'
          description: OK
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Add permissions to group
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: 'Add a permission to a group. Permissions are strings associated with the group that some resources requires to fulfill requests.


        Examples of `Permissions`:


        - `ACCESS_APPLICATIONS`

        - `ACCESS_INFRASTRUCTURE`

        - `ACCESS_KUBERNETES`

        - `ACCESS_MOBILE_APPS`

        - `ACCESS_WEBSITES`

        - `CAN_CONFIGURE_AGENT_RUN_MODE`

        - `CAN_CONFIGURE_AGENTS`

        - `CAN_CONFIGURE_API_TOKENS`

        - `CAN_CONFIGURE_APPLICATIONS`

        - `CAN_CONFIGURE_AUTHENTICATION_METHODS`

        - `CAN_CONFIGURE_CUSTOM_ALERTS`

        - `CAN_CONFIGURE_EUM_APPLICATIONS`

        - `CAN_CONFIGURE_GLOBAL_ALERT_CONFIGS`

        - `CAN_CONFIGURE_GLOBAL_ALERT_PAYLOAD`

        - `CAN_CONFIGURE_INTEGRATIONS`

        - `CAN_CONFIGURE_LOG_MANAGEMENT`

        - `CAN_CONFIGURE_MOBILE_APP_MONITORING`

        - `CAN_CONFIGURE_PERSONAL_API_TOKENS`

        - `CAN_CONFIGURE_RELEASES`

        - `CAN_CONFIGURE_SERVICE_LEVEL_INDICATORS`

        - `CAN_CONFIGURE_SERVICE_MAPPING`

        - `CAN_CONFIGURE_SESSION_SETTINGS`

        - `CAN_CONFIGURE_TEAMS`

        - `CAN_CONFIGURE_USERS`

        - `CAN_CREATE_PUBLIC_CUSTOM_DASHBOARDS`

        - `CAN_EDIT_ALL_ACCESSIBLE_CUSTOM_DASHBOARDS`

        - `CAN_INSTALL_NEW_AGENTS`

        - `CAN_VIEW_ACCOUNT_AND_BILLING_INFORMATION`

        - `CAN_VIEW_AUDIT_LOG`

        - `CAN_VIEW_LOGS`

        - `CAN_VIEW_TRACE_DETAILS`

        - `LIMITED_APPLICATIONS_SCOPE`

        - `LIMITED_INFRASTRUCTURE_SCOPE`

        - `LIMITED_KUBERNETES_SCOPE`

        - `LIMITED_MOBILE_APPS_SCOPE`

        - `LIMITED_WEBSITES_SCOPE`

        '
  /api/settings/rbac/groups/{groupId}/users:
    put:
      operationId: addUsersToGroup
      parameters:
      - description: Id of the group to add users
        example: groupId
        in: path
        name: groupId
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            example:
            - userId1
            - userId3
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                id: groupId
                name: group name
                members:
                - userId: userId1
                  email: username1@example.com
                - userId: userId2
                  email: username2@example.com
                - userId: userId3
                  email: username3@example.com
                permissionSet:
                  permissions:
                  - CAN_VIEW_LOGS
                  applicationIds: []
                  kubernetesClusterUUIDs: []
                  kubernetesNamespaceUIDs: []
                  websiteIds: []
                  mobileAppIds: []
                  syntheticTestIds: []
                  infraDfqFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
                  actionFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
              schema:
                $ref: '#/components/schemas/ApiGroup'
          description: OK
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Add users to group
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: Add one or more users to a group. The array contains the ids of the users to be added.
  /api/settings/rbac/groups/{id}:
    delete:
      description: 'Delete the group data.

        For more information on groups please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#groups.'
      operationId: deleteGroup
      parameters:
      - description: Id of the group to delete
        example: groupId
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        default:
          content:
            application/json: {}
          description: default response
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Delete group
      tags:
      - Groups
      x-ibm-ahub-byok: true
    get:
      operationId: getGroup
      parameters:
      - description: Id of the group for retrieval
        example: groupId
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                id: groupId
                name: group name
                members:
                - userId: userId
                  email: username@example.com
                permissionSet:
                  permissions:
                  - ACCESS_INFRASTRUCTURE
                  - LIMITED_WEBSITES_SCOPE
                  - CAN_VIEW_SYNTHETIC_TESTS
                  - CAN_VIEW_SYNTHETIC_LOCATIONS
                  - CAN_VIEW_TRACE_DETAILS
                  - CAN_CONFIGURE_AGENT_RUN_MODE
                  - CAN_CONFIGURE_AUTOMATION_ACTIONS
                  - CAN_CONFIGURE_USERS
                  - ACCESS_SYNTHETICS
                  - CAN_VIEW_LOGS
                  - LIMITED_KUBERNETES_SCOPE
                  - CAN_CONFIGURE_TEAMS
                  - CAN_VIEW_SYNTHETIC_TEST_RESULTS
                  - LIMITED_SYNTHETICS_SCOPE
                  - LIMITED_INFRASTRUCTURE_SCOPE
                  applicationIds:
                  - scopeId: scopeId1
                    scopeRoleId: '-102'
                  - scopeId: scopeId2
                    scopeRoleId: '-102'
                  - scopeId: scopeId3
                    scopeRoleId: '-102'
                  - scopeId: scopeId4
                    scopeRoleId: '-102'
                  - scopeId: scopeId5
                    scopeRoleId: '-102'
                  - scopeId: scopeId6
                    scopeRoleId: '-102'
                  kubernetesClusterUUIDs: []
                  kubernetesNamespaceUIDs: []
                  websiteIds: []
                  mobileAppIds: []
                  syntheticTestIds:
                  - scopeId: scopeId10
                    scopeRoleId: '-1'
                  restrictedApplicationFilter:
                    label: filter name
                    tagFilterExpression:
                      type: TAG_FILTER
                      name: service.name
                      stringValue: acceptor
                      numberValue: null
                      booleanValue: null
                      key: null
                      value: acceptor
                      operator: EQUALS
                      entity: DESTINATION
                    scope: INCLUDE_NO_DOWNSTREAM
                  infraDfqFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
                  actionFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
              schema:
                $ref: '#/components/schemas/ApiGroup'
          description: OK
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Get group
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: Returns group data, including the `Permission set`. See [get groups](#operation/getGroups) for more details.
    put:
      operationId: updateGroup
      parameters:
      - description: Id of the group to update
        example: groupId
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              name: group name
              members:
              - userId: userId
                email: username@example.com
              permissionSet:
                permissions:
                - CAN_VIEW_LOGS
                applicationIds:
                - scopeId: scopeId1
                  scopeRoleId: '-102'
                kubernetesClusterUUIDs: []
                kubernetesNamespaceUIDs: []
                websiteIds: []
                mobileAppIds: []
                syntheticTestIds:
                - scopeId: scopeId10
                  scopeRoleId: '-1'
                restrictedApplicationFilter:
                  label: group name
                  tagFilterExpression:
                    type: TAG_FILTER
                    name: service.name
                    stringValue: acceptor
                    numberValue: null
                    booleanValue: null
                    key: null
                    value: acceptor
                    operator: EQUALS
                    entity: DESTINATION
                  scope: INCLUDE_NO_DOWNSTREAM
                infraDfqFilter:
                  scopeId: ''
                  scopeRoleId: '-1'
                actionFilter:
                  scopeId: ''
                  scopeRoleId: '-1'
            schema:
              $ref: '#/components/schemas/ApiGroup'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                name: group name
                members:
                - userId: userId
                  email: username@example.com
                permissionSet:
                  permissions:
                  - CAN_VIEW_LOGS
                  applicationIds:
                  - scopeId: scopeId1
                    scopeRoleId: '-102'
                  kubernetesClusterUUIDs: []
                  kubernetesNamespaceUIDs: []
                  websiteIds: []
                  mobileAppIds: []
                  syntheticTestIds:
                  - scopeId: scopeId10
                    scopeRoleId: '-1'
                  restrictedApplicationFilter:
                    label: group name
                    tagFilterExpression:
                      type: TAG_FILTER
                      name: service.name
                      stringValue: acceptor
                      numberValue: null
                      booleanValue: null
                      key: null
                      value: acceptor
                      operator: EQUALS
                      entity: DESTINATION
                    scope: INCLUDE_NO_DOWNSTREAM
                  infraDfqFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
                  actionFilter:
                    scopeId: ''
                    scopeRoleId: '-1'
              schema:
                $ref: '#/components/schemas/ApiGroup'
          description: OK
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Update group
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: 'Add a permission to a group. Permissions are strings associated with the group that some resources requires to fulfill requests.


        Examples of `Permissions`:


        - `ACCESS_APPLICATIONS`

        - `ACCESS_INFRASTRUCTURE`

        - `ACCESS_KUBERNETES`

        - `ACCESS_MOBILE_APPS`

        - `ACCESS_WEBSITES`

        - `CAN_CONFIGURE_AGENT_RUN_MODE`

        - `CAN_CONFIGURE_AGENTS`

        - `CAN_CONFIGURE_API_TOKENS`

        - `CAN_CONFIGURE_APPLICATIONS`

        - `CAN_CONFIGURE_AUTHENTICATION_METHODS`

        - `CAN_CONFIGURE_CUSTOM_ALERTS`

        - `CAN_CONFIGURE_EUM_APPLICATIONS`

        - `CAN_CONFIGURE_GLOBAL_ALERT_CONFIGS`

        - `CAN_CONFIGURE_GLOBAL_ALERT_PAYLOAD`

        - `CAN_CONFIGURE_INTEGRATIONS`

        - `CAN_CONFIGURE_LOG_MANAGEMENT`

        - `CAN_CONFIGURE_MOBILE_APP_MONITORING`

        - `CAN_CONFIGURE_PERSONAL_API_TOKENS`

        - `CAN_CONFIGURE_RELEASES`

        - `CAN_CONFIGURE_SERVICE_LEVEL_INDICATORS`

        - `CAN_CONFIGURE_SERVICE_MAPPING`

        - `CAN_CONFIGURE_SESSION_SETTINGS`

        - `CAN_CONFIGURE_TEAMS`

        - `CAN_CONFIGURE_USERS`

        - `CAN_CREATE_PUBLIC_CUSTOM_DASHBOARDS`

        - `CAN_EDIT_ALL_ACCESSIBLE_CUSTOM_DASHBOARDS`

        - `CAN_INSTALL_NEW_AGENTS`

        - `CAN_VIEW_ACCOUNT_AND_BILLING_INFORMATION`

        - `CAN_VIEW_AUDIT_LOG`

        - `CAN_VIEW_LOGS`

        - `CAN_VIEW_TRACE_DETAILS`

        - `LIMITED_APPLICATIONS_SCOPE`

        - `LIMITED_INFRASTRUCTURE_SCOPE`

        - `LIMITED_KUBERNETES_SCOPE`

        - `LIMITED_MOBILE_APPS_SCOPE`

        - `LIMITED_WEBSITES_SCOPE`

        '
  /api/settings/rbac/groups/{id}/user/{userId}:
    delete:
      description: 'Remove the user from a group.

        For more information on groups please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#groups.'
      operationId: removeUserFromGroup
      parameters:
      - description: Id of the group to remove user from
        example: groupId
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Id of the user to remove
        example: userId
        in: path
        name: userId
        required: true
        schema:
          type: string
      responses:
        default:
          content:
            application/json: {}
          description: default response
      security:
      - ApiKeyAuth:
        - CanConfigureTeams
      summary: Remove user from group
      tags:
      - Groups
      x-ibm-ahub-byok: true
  /api/settings/rbac/mappings:
    get:
      operationId: getGroupMappings
      responses:
        '200':
          content:
            application/json:
              example:
              - id: mappingId
                key: roles
                value: analyst
                groupId: '-3'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupMapping'
          description: OK
        '404':
          description: No group mapping found
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Get all group mappings
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: 'If mappings between groups on the identity provider (LDAP, OIDC, SAML) and Instana groups where configured, this will return a list of those mappings.


        This can be configured through the [api](#operation/createGroupMapping) or on Instana graphical user interface at Settings > Authentication > IDENTITY PROVIDERS > Group Mapping.'
    post:
      operationId: createGroupMapping
      requestBody:
        content:
          application/json:
            example:
              key: roles
              value: analyst
              groupId: '-3'
            schema:
              $ref: '#/components/schemas/GroupMapping'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                id: mappingId
                key: roles
                value: analyst
                groupId: '-3'
              schema:
                $ref: '#/components/schemas/GroupMapping'
          description: OK
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Create group mapping
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: 'Creates a mapping between a group from the IdP (LDAP, OIDC, SAML) and an Instana group.


        If the IdP is configured and mappings are enabled, the `key` `value` pairs a user sent by the idp will be evaluated every time this user logs in.


        If they match the mapping, the user will be assigned to the group corresponding to the `groupId`.


        Inside the payload, the `id` for the mapping is ignored, and instead, Instana generates a new id.'
  /api/settings/rbac/mappings/delete:
    put:
      operationId: deleteGroupMappings
      requestBody:
        content:
          application/json:
            example:
            - firstid
            - secondid
            schema:
              type: string
        required: true
      responses:
        '204':
          description: OK
        '422':
          description: invalid request
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Delete multiple group mappings
      tags:
      - Groups
      x-ibm-ahub-byok: true
  /api/settings/rbac/mappings/identityProvider/restrictEmptyIdpGroups:
    get:
      operationId: getIdentityProviderPatch
      responses:
        '200':
          content:
            application/json:
              example:
                restrictEmptyIdpGroups: false
              schema:
                $ref: '#/components/schemas/IdentityProviderPatch'
          description: OK
        '404':
          description: No group mapping restriction found
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Check user restrictions for empty Idp group mapping
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: Returns `RestrictEmptyIdpGroups` value indicating if access is denied for empty Idp group mapping. `RestrictEmptyIdpGroups = true` indicates that the tenant is locked and only those users are allowed access that have at least one working mapping rule applied to them during the login process.
    put:
      operationId: updateIdentityProvider
      requestBody:
        content:
          application/json:
            example:
              restrictEmptyIdpGroups: true
            schema:
              $ref: '#/components/schemas/IdentityProviderPatch'
        required: true
      responses:
        default:
          content:
            application/json: {}
          description: default response
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Allow/Restrict users with empty Idp group mapping
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: Set the RestrictEmptyIdpGroups value as true/false. See [Check user restrictions for empty Idp group mapping](#operation/getIdentityProviderPatch) for more details.
  /api/settings/rbac/mappings/overview:
    get:
      operationId: getGroupMappingsOverview
      responses:
        '200':
          content:
            application/json:
              example:
              - id: mappingId
                key: roles
                value: analyst
                role: default
                team: testing
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupMappingOverview'
          description: OK
        '404':
          description: No group mapping overviews found
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Get all group mappings overview
      tags:
      - Groups
      x-ibm-ahub-byok: true
  /api/settings/rbac/mappings/{id}:
    delete:
      operationId: deleteGroupMapping
      parameters:
      - description: Id of the group mapping to delete
        example: mappingId
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        default:
          content:
            application/json: {}
          description: default response
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Delete group mapping
      tags:
      - Groups
      x-ibm-ahub-byok: true
    get:
      operationId: getGroupMapping
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                id: mappingId
                key: roles
                value: analyst
                groupId: '-3'
              schema:
                $ref: '#/components/schemas/GroupMapping'
          description: OK
        '404':
          description: No group mapping found
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Get group mapping
      tags:
      - Groups
      x-ibm-ahub-byok: true
    put:
      operationId: updateGroupMapping
      parameters:
      - description: Id of the group mapping to update
        example: mappingId
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              id: mappingId
              key: roles
              value: analyst
              groupId: '-3'
            schema:
              $ref: '#/components/schemas/GroupMapping'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                id: mappingId
                key: roles
                value: analyst
                groupId: '-3'
              schema:
                $ref: '#/components/schemas/GroupMapping'
          description: OK
      security:
      - ApiKeyAuth:
        - CanConfigureAuthenticationMethods
      summary: Update group mapping
      tags:
      - Groups
      x-ibm-ahub-byok: true
      description: See [creating group mapping](#operation/createGroupMapping)
components:
  schemas:
    ScopeBinding:
      type: object
      properties:
        scopeId:
          type: string
          maxLength: 64
          minLength: 0
        scopeRoleId:
          type: string
          maxLength: 64
          minLength: 0
    GroupMapping:
      type: object
      properties:
        groupId:
          type: string
        id:
          type: string
          maxLength: 64
          minLength: 0
        key:
          type: string
          maxLength: 65536
          minLength: 0
        teamId:
          type: string
          maxLength: 64
          minLength: 5
        value:
          type: string
          maxLength: 65536
          minLength: 0
      required:
      - groupId
      - key
      - value
    GroupMappingOverview:
      type: object
      properties:
        id:
          type: string
        key:
          type: string
        role:
          type: string
        team:
          type: string
        value:
          type: string
    ApiMember:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
        userId:
          type: string
      required:
      - userId
    ApiRestrictedApplicationFilter:
      type: object
      properties:
        label:
          type: string
        restrictingApplicationId:
          type: string
        scope:
          type: string
          enum:
          - INCLUDE_NO_DOWNSTREAM
          - INCLUDE_IMMEDIATE_DOWNSTREAM_DATABASE_AND_MESSAGING
          - INCLUDE_ALL_DOWNSTREAM
        tagFilterExpression:
          $ref: '#/components/schemas/TagFilterExpressionElement'
    ApiCreateGroup:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/ApiMember'
          uniqueItems: true
        name:
          type: string
        permissionSet:
          $ref: '#/components/schemas/ApiPermissionSet'
      required:
      - members
      - name
      - permissionSet
    ApiGroup:
      type: object
      properties:
        id:
          type: string
          maxLength: 64
          minLength: 0
        members:
          type: array
          items:
            $ref: '#/components/schemas/ApiMember'
          uniqueItems: true
        name:
          type: string
        permissionSet:
          $ref: '#/components/schemas/ApiPermissionSet'
      required:
      - id
      - members
      - name
      - permissionSet
    TagFilterExpressionElement:
      type: object
      description: Boolean expression of tag filters to define the scope of relevant calls.
      discriminator:
        mapping:
          EXPRESSION: '#/components/schemas/TagFilterExpression'
          TAG_FILTER: '#/components/schemas/TagFilter'
        propertyName: type
      properties:
        type:
          type: string
      required:
      - type
    ApiPermissionSet:
      type: object
      properties:
        actionFilter:
          $ref: '#/components/schemas/ScopeBinding'
        applicationIds:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        businessPerspectiveIds:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        infraDfqFilter:
          $ref: '#/components/schemas/ScopeBinding'
        kubernetesClusterUUIDs:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        kubernetesNamespaceUIDs:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        mobileAppIds:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        permissions:
          type: array
          items:
            type: string
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        restrictedApplicationFilter:
          $ref: '#/components/schemas/ApiRestrictedApplicationFilter'
        sloIds:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        syntheticCredentialKeys:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        syntheticTestIds:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
        websiteIds:
          type: array
          items:
            $ref: '#/components/schemas/ScopeBinding'
          maxItems: 1024
          minItems: 0
          uniqueItems: true
      required:
      - applicationIds
      - businessPerspectiveIds
      - infraDfqFilter
      - kubernetesClusterUUIDs
      - kubernetesNamespaceUIDs
      - mobileAppIds
      - permissions
      - sloIds
      - syntheticCredentialKeys
      - syntheticTestIds
      - websiteIds
    IdentityProviderPatch:
      type: object
      properties:
        restrictEmptyIdpGroups:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: authorization
      type: apiKey
      description: "## Example\n\n```bash\ncurl --request GET \\\n  --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n  --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n"
x-tagGroups:
- name: Websites & Mobile Apps
  tags:
  - Website Metrics
  - Website Catalog
  - Website Analyze
  - Website Configuration
  - Mobile App Metrics
  - Mobile App Catalog
  - Mobile App Analyze
  - Mobile App Configuration
  - End User Monitoring
- name: Applications
  tags:
  - Application Metrics
  - Application Resources
  - Application Catalog
  - Application Analyze
  - Application Settings
  - Application Topology
  - Application Alert Configuration
  - Global Application Alert Configuration
- name: Infrastructure
  tags:
  - Infrastructure Analyze
  - Infrastructure Metrics
  - Infrastructure Resources
  - Infrastructure Catalog
  - Infrastructure Topology
- name: Logging
  tags:
  - Logging Analyze
- name: Synthetic Monitoring
  tags:
  - Synthetic Catalog
  - Synthetic Metrics
  - Synthetic Settings
  - Synthetic Test Playback Results
  - Synthetic Alert Configuration
- name: Logs
  tags:
  - Log Alert Configuration
- name: Events
  tags:
  - Events
  - Event Settings
- name: Automation
  tags:
  - Action Catalog
  - Action History
  - Policies
- name: Service Levels
  tags:
  - SLI Settings
  - SLI Report
  - Apdex Settings
  - Apdex Report
  - Service Levels Objective(SLO) Configurations
  - Service Levels Objective(SLO) Report
  - Service Levels Alert Configuration
  - SLO Correction Configurations
  - SLO Correction Windows
- name: AI Management
  tags:
  - AI Management
- name: Settings
  tags:
  - Custom Dashboards
  - User
  - Groups
  - Teams
  - Roles
  - Audit Log
  - API Token
  - Maintenance Configuration
  - Synthetic Calls
  - Session Settings
  - Automation Settings
  - Authentication
- name: Open Beta Features
  tags:
  - Infrastructure Analyze
- name: Closed Beta Features
  tags:
  - Infrastructure Alert Configuration
- name: Instana
  tags:
  - Releases
  - Host Agent
  - Health
  - Usage