> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduktor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure application groups across environments

> Stop an application instance API key changing application groups in other environments: check your exposure, move CI to application API keys, go strict.

## Overview

An application instance API key is scoped to one environment of a Self-service application, such as `orders-dev`. Before Console 1.49.0, that key could create and change **application groups**, and an application group grants permissions on *any* instance of its application. So a key issued for a development environment could grant access to a production environment of the same application.

Console 1.49.0 adds a correctly scoped credential, a diagnostic to check whether this happened in your organization, and an opt-in setting that closes the gap. You can turn the setting on at your own pace, after you move your pipelines to the new credential.

This guide shows how to check whether you're affected, move your pipelines to application API keys, and turn on strict security.

## Who is affected

You're only affected if your application owners have distributed application instance API keys to lower-privileged environments and those keys also manage application groups, typically from continuous integration (CI). A key that only manages its own environment's topics, subjects and connectors never reached beyond its environment.

The business risk is real where it applies: a key trusted to a development pipeline could grant a user or an external group access to the production environment of the same application, through an application group. The [diagnostic](#check-whether-youre-affected) tells you whether any key actually did this.

The following example shows the problem. The `orders-dev` key applies `orders-app-group`, and that group's `permissions` and `instancePermissions` reach both `orders-dev` and `orders-prod`, so the development key changes who can reach production.

```mermaid theme={null}
flowchart LR
  key["orders-dev instance key<br/>(development environment)"]
  group["ApplicationGroup orders-app-group<br/>targets orders-dev and orders-prod"]
  dev["orders-dev environment"]
  prod["orders-prod environment"]

  key -->|"applies the group"| group
  group -->|"legitimate: the key's own environment"| dev
  group -->|"overreach: a development key grants access to production"| prod
```

Here is the application group behind the diagram. The development key applies it, yet it grants roles on `orders-prod` as well:

```yaml theme={null}
---
apiVersion: self-serve/v1
kind: ApplicationGroup
metadata:
  application: "orders-app"
  name: "orders-app-group"
spec:
  displayName: Orders support
  description: |
    Members of the orders support group are allowed:
      Read access on all the resources
      Can request and grant access
  instancePermissions:
    - appInstance: orders-dev
      permissions: ["applicationInstancePermissionRequestAccess", "applicationInstancePermissionGrantAccess"]
    - appInstance: orders-prod
      permissions: ["applicationInstancePermissionRequestAccess", "applicationInstancePermissionGrantAccess", "applicationInstanceApiKeyManage"]
  permissions:
    - appInstance: orders-dev
      resourceType: TOPIC
      patternType: "LITERAL"
      name: "*"
      permissions: ["topicViewConfig", "topicConsume"]
    - appInstance: orders-prod
      resourceType: CONSUMER_GROUP
      patternType: "LITERAL"
      name: "*"
      permissions: ["consumerGroupCreate", "consumerGroupReset", "consumerGroupDelete", "consumerGroupView"]
  members:
    - user1@company.org
    - user2@company.org
  externalGroups:
    - GP-COMPANY-ORDERS-SUPPORT
  externalGroupRegex:
    - GP-COMPANY*
```

## Application API keys: the correctly scoped credential

An **application API key** is a credential scoped to the application itself, not to one of its instances. Use it for one job: manage the application's application groups from CI. It can read the application and manage its application groups, across every instance. It has no access to Kafka resources (topics, subjects, connectors, consumer groups) and can't create other keys.

Keep using **application instance API keys** for everything else. The split is deliberate: an application API key is only for managing application groups through automation, and an application instance API key is for everything within a single environment.

Only an owner of the application can create an application API key, the same people who already manage its application groups. Because one application API key manages application groups across *all* of the application's instances, be mindful of who you give it to and how you distribute it through your organization. Treat it as a cross-environment credential, store it in a secret manager, and give it only to the pipeline that applies application groups.

Create and manage application API keys in the **API Keys** tab of the application details page, or through the API:

* `POST /token/v1/application_tokens/{application-name}` creates a key. Set the optional `expiresAt` to give it an expiry date.
* `GET /token/v1/application_tokens/{application-name}` lists the keys with their status: `Active`, `Expired` or `Revoked`.
* `POST /token/v1/{token-id}/revoke` revokes a key. It stops working immediately and stays in the list.

The [Conduktor CLI](https://docs.conduktor.io/guide/conduktor-in-production/automate/cli-automation.md) manages these keys too, so CI can create and revoke them as part of a pipeline:

```bash theme={null}
# authenticate as an application owner, then:
conduktor token create application --application=orders-app orders-ci
conduktor token list application --application=orders-app
conduktor token revoke <token-id>
```

The CLI accepts an application API key as `CDK_API_KEY` for the commands that apply application groups. Create admin and application instance keys with `conduktor token create admin` and `conduktor token create application-instance`.

## Check whether you're affected

Console includes a diagnostic that answers the question from your audit log, so you don't read raw events. Go to **Settings** > **Diagnostics** > **App group security** (available to platform administrators).

The page reports either that your organization is not affected, or that it is, with a table of the environments an instance key reached beyond its own. To build it, the diagnostic reads the audit log for application-group create and change events made by an application instance key, reads the instances each of those groups targeted, and compares them against the key's own instance. An instance other than the key's own is an overreach. A group that only touched its own instance is legitimate and isn't reported. The check reads the audit log only and makes no changes.

## Turn on strict security

Once your pipelines use application API keys to manage application groups, turn on strict application group security. With it on, an application instance API key can no longer create or change application groups, which closes the gap for good. Users, application API keys and admin API keys are unaffected.

> [!WARNING]
>
> Establish whether you're affected before you turn this on. Once the setting is on, any CI pipeline that applies an application group with an application instance API key starts to fail: the apply returns a `403` response. This includes application groups that only reference the key's own environment, not just the cross-environment ones the setting is there to stop.
>
> Run the [diagnostic](#check-whether-youre-affected) first. If it shows that application instance keys manage application groups, move those pipelines to application API keys before you turn the setting on, or their applies will break.

Set `application_group_strict_security` to `true` (`CDK_APPLICATIONGROUPSTRICTSECURITY=true`) in your Console configuration. It's off by default, so upgrading to Console 1.49.0 changes nothing until you turn it on. See [Global properties](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-console/environment-variables.md#global-properties) for the setting.

With it on, an application instance API key that tries to create or change an application group gets a `403` response that points to application API keys.

## Summary

1. Run the diagnostic under **Settings** > **Diagnostics** > **App group security** to find out whether an application instance key reached beyond its own environment.
2. Review the application groups it lists and, where needed, re-create them with an application API key.
3. Move your pipelines to application API keys for application-group changes.
4. Turn on `application_group_strict_security`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.