---
name: secrets-manager-secret-groups
title: Organizing your secrets
description: When you work with IBM Cloud® Secrets Manager, you can create groups to organize your secrets and control who on your team has access to them. Then, if you don't need them anymore, you can delete the groups.
last-updated: 2026-05-11
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/secrets-manager?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

{:codeblock: .codeblock}
{:screen: .screen}
{:download: .download}
{:external: target="_blank" .external}
{:faq: data-hd-content-type='faq'}
{:gif: data-image-type='gif'}
{:important: .important}
{:note: .note}
{:pre: .pre}
{:tip: .tip}
{:preview: .preview}
{:deprecated: .deprecated}
{:beta: .beta}
{:term: .term}
{:shortdesc: .shortdesc}
{:script: data-hd-video='script'}
{:support: data-reuse='support'}
{:table: .aria-labeledby="caption"}
{:troubleshoot: data-hd-content-type='troubleshoot'}
{:help: data-hd-content-type='help'}
{:tsCauses: .tsCauses}
{:tsResolve: .tsResolve}
{:tsSymptoms: .tsSymptoms}
{:video: .video}
{:step: data-tutorial-type='step'}
{:tutorial: data-hd-content-type='tutorial'}
{:api: .ph data-hd-interface='api'}
{:cli: .ph data-hd-interface='cli'}
{:ui: .ph data-hd-interface='ui'}
{:terraform: .ph data-hd-interface="terraform"}
{:curl: .ph data-hd-programlang='curl'}
{:java: .ph data-hd-programlang='java'}
{:ruby: .ph data-hd-programlang='ruby'}
{:c#: .ph data-hd-programlang='c#'}
{:objectc: .ph data-hd-programlang='Objective C'}
{:python: .ph data-hd-programlang='python'}
{:javascript: .ph data-hd-programlang='javascript'}
{:php: .ph data-hd-programlang='PHP'}
{:swift: .ph data-hd-programlang='swift'}
{:curl: .ph data-hd-programlang='curl'}
{:dotnet-standard: .ph data-hd-programlang='dotnet-standard'}
{:go: .ph data-hd-programlang='go'}
{:unity: .ph data-hd-programlang='unity'}
{:release-note: data-hd-content-type='release-note'}

# Organizing your secrets
{: #secret-groups}

When you work with IBM Cloud® Secrets Manager, you can create groups to organize your secrets and control who on your team has access to them. Then, if you don't need them anymore, you can delete the groups.
{: shortdesc}

Similar to the way that [resource groups](#x2161955){: term} help to ensure correct policy enforcement at the platform level, you can create secret groups at the instance level to organize secrets.

![The image shows two examples of a secret group and how they're mapped to access groups. One where the reader role is assigned and one where the manager role is assigned. The content is explained fully in the surrounding text.](/images/secret-group.svg){: caption="Assigning access to secret groups" caption-side="bottom"}

As shown in the previous image, users with *Reader* access to a secret group can see that the group exists and understand which secrets are assigned to it. Users with *Writer* access can view and edit the secret group and secrets themselves. By design, the default secret group inherits the same permissions that are set for the instance.

You can choose to group your secrets by phase of development, specific to the type of roles that people on your team have, or in any way that might help you. Each secret can be mapped to one group only and the mapping occurs at the time of secret creation.

To learn about the suggested guidelines for using secret groups, check out [Best practices for organizing secrets and assigning access](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-best-practices-organize-secrets&format=markdown).
{: tip}

## Before you begin
{: #before-secret-groups}

Before you begin, be sure that you have the required level of access. To create and manage secret groups, you need the [**Manager** service role](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam&format=markdown).

## Creating secret groups
{: #create-secret-groups}

You can create secret groups by using the Secrets Manager console, CLI, or API.

### Creating secret groups in the UI
{: #create-group-ui}
{: ui}

You can create secret groups by using the console. You can also create a secret group during the process of adding or creating a secret.

1. In the console, click the **Menu** icon ![Menu icon](../icons/icon_hamburger.svg) **> Resource List**.
2. From the list of services, select your instance of Secrets Manager.
3. In the navigation, click **Secret groups > Create**.
4. Add a name and description to easily identify your group.
5. Click **Create**.
6. Optional: Assign your secret group an [IAM policy](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-assign-access&format=markdown).

### Creating secret groups from the CLI
{: #create-group-cli}
{: cli}

You can create secret groups by using the Secrets Manager CLI plug-in.

To create a secret group, run the [**`ibmcloud secrets-manager secret-group-create`**](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli&format=markdown#secrets-manager-cli-secret-group-create-command) command.

```sh
ibmcloud secrets-manager secret-group-create --name "my-secret-group" --description "Extended description for this group."
```
{: pre}

The command outputs the ID value of the secret group, along with other metadata. For more information about the command options, see [**`ibmcloud secrets-manager secret-group-create`**](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli&format=markdown#secrets-manager-cli-secret-group-create-command).

### Creating secret groups with the API
{: #create-group-api}
{: api}

You can create secret groups by using the Secrets Manager API.

The following example request creates a secret group. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.
{: curl}


```sh
curl -X POST 
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
    "name":"my-secret-group",
    "description":"Extended description for this group."
    }' \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secret_groups"
```
{: codeblock}
{: curl}


### Creating secret groups with Terraform
{: #create-group-terraform}
{: terraform}

You can create secret groups by using Terraform for Secrets Manager.

The following example request creates a secret group.

```terraform
resource "ibm_sm_secret_group" "sm_secret_group_test" {
  instance_id = local.instance_id
  region = local.region
  name = "secret_group_test"
  description = "example secret group"
}
```
{: codeblock}

Organize secrets efficiently using Terraform IBM Modules (TIM) for [Secrets Manager Secret Group](https://registry.terraform.io/modules/terraform-ibm-modules/secrets-manager-secret-group/ibm/latest){: external} to create and manage secret groups. Learn more about [Terraform IBM Modules](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-about-tim&format=markdown).
{: tip}

## Deleting secret groups
{: #delete-groups}

If you no longer need to use a group, you can delete it by using the console, CLI, or API.

To delete a secret group, it must be empty. If you need to remove a secret group that contains secrets, you must first [delete the secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-delete-secrets&format=markdown) that are part of the group.
{: note}


### Deleting secret groups in the UI
{: #delete-group-ui}
{: ui}

You can delete secret groups by using the console.

1. In the console, click the **Menu** icon ![Menu icon](../icons/icon_hamburger.svg) **> Resource List**.
2. From the list of services, select your instance of Secrets Manager.
3. In the navigation, click **Secret groups**.
4. In the row for the secret group that you want to delete, click the **Actions** icon ![Actions icon](../icons/actions-icon-vertical.svg).
5. Click **Delete group**.
6. Click **Delete**.

### Deleting secret groups from the CLI
{: #delete-group-cli}
{: cli}

You can delete secret groups by using the Secrets Manager CLI plug-in.

To delete a secret group, run the [**`ibmcloud secrets-manager secret-group-delete`**](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli&format=markdown#secrets-manager-cli-secret-group-delete-command) command. You can specify the secret group by using either its ID or name.

Delete by ID:

```sh
ibmcloud secrets-manager secret-group-delete --id SECRET_GROUP_ID
```
{: pre}

For more information about the command options, see [**`ibmcloud secrets-manager secret-group-delete`**](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli&format=markdown#secrets-manager-cli-secret-group-delete-command).

### Deleting secret groups with the API
{: #delete-group-api}
{: api}

You can delete secret groups by using the Secrets Manager API.

The following example request deletes a secret group. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.
{: curl}


```bash
curl -X DELETE 
  --H "Authorization: Bearer {iam_token}" \ 
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secret_groups/{id}"
```
{: codeblock}
{: curl}


## Next steps
{: #secret-groups-next-steps}

Already using secret groups? To learn more about assigning access and organizing your secrets, check out the following resources.

- [Assigning access to a secret group](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-assign-access&format=markdown#assign-access-secret-group)
- [Best practices for organizing secrets and assigning access](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-best-practices-organize-secrets&format=markdown)
- To automate Secrets Manager secret group management with Terraform, see Terraform IBM Modules (TIM) for [Secrets Manager Secret Group](https://registry.terraform.io/modules/terraform-ibm-modules/secrets-manager-secret-group/ibm/latest){: external}.