IBM Cloud API Docs

Introduction

Last updated: 2022-12-09

With IBM Cloud® Secrets Manager, you can create, lease, and centrally manage secrets that are used in IBM Cloud services or your custom-built applications. Secrets are stored in a dedicated instance of Secrets Manager that is built on open source HashiCorp Vault.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries.

For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub. For more information about getting started with Secrets Manager, check out the docs. If you haven't upgraded to this version of the API yet, you can still access Version 1.0, which is deprecated.

Installing the Java SDK

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>secrets-manager-sdk</artifactId>
    <version>${version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:secrets-manager-sdk:${version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/secrets-manager-java-sdk

Installing the Python SDK

pip install --upgrade "ibm-secrets-manager-sdk"

View on GitHub

https://github.com/IBM/secrets-manager-python-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
  "github.com/IBM/secrets-manager-go-sdk/secretsmanagerv2"
)

Go get

go get -u github.com/IBM/secrets-manager-go-sdk

View on GitHub

https://github.com/IBM/secrets-manager-go-sdk

Installing the Node SDK

npm install @ibm-cloud/secrets-manager

View on GitHub

https://github.com/IBM/secrets-manager-node-sdk

Endpoint URLs

Secrets Manager supports instance-specific endpoint URLs that you can use to interact with the service over public or private service endpoints. To make requests to the API, you supply the instance ID that is unique to your Secrets Manager service instance.

You can copy your endpoint URL from the Endpoints page in the Secrets Manager service dashboard.

Endpoint URLs by location

  • Dallas: https://{instance_ID}.us-south.secrets-manager.appdomain.cloud
  • Frankfurt: https://{instance_ID}.eu-de.secrets-manager.appdomain.cloud
  • London: https://{instance_ID}.eu-gb.secrets-manager.appdomain.cloud
  • Osaka: https://{instance_ID}.jp-osa.secrets-manager.appdomain.cloud
  • Sao Paulo: https://{instance_ID}.br-sao.secrets-manager.appdomain.cloud
  • Sydney: https://{instance_ID}.au-syd.secrets-manager.appdomain.cloud
  • Tokyo: https://{instance_ID}.jp-tok.secrets-manager.appdomain.cloud
  • Toronto: https://{instance_ID}.ca-tor.secrets-manager.appdomain.cloud
  • Washington DC: https://{instance_ID}.us-east.secrets-manager.appdomain.cloud

Secrets Manager supports instance-specific endpoint URLs that you can use to interact with the service over public or private service endpoints. To target your Secrets Manager service instance by using the Java SDK, use the setServiceUrl() method. You can copy your endpoint URL from the Endpoints page in the Secrets Manager service dashboard.

If you copy the endpoint URL from your Secrets Manager service dashboard, be sure to add /api to the URL to use it with the SDK.

Endpoint URLs by location

  • Dallas: https://{instance_ID}.us-south.secrets-manager.appdomain.cloud
  • Frankfurt: https://{instance_ID}.eu-de.secrets-manager.appdomain.cloud
  • London: https://{instance_ID}.eu-gb.secrets-manager.appdomain.cloud
  • Osaka: https://{instance_ID}.jp-osa.secrets-manager.appdomain.cloud
  • Sao Paulo: https://{instance_ID}.br-sao.secrets-manager.appdomain.cloud
  • Sydney: https://{instance_ID}.au-syd.secrets-manager.appdomain.cloud
  • Tokyo: https://{instance_ID}.jp-tok.secrets-manager.appdomain.cloud
  • Toronto: https://{instance_ID}.ca-tor.secrets-manager.appdomain.cloud
  • Washington DC: https://{instance_ID}.us-east.secrets-manager.appdomain.cloud

Secrets Manager supports instance-specific endpoint URLs that you can use to interact with the service over public or private service endpoints. To target your Secrets Manager service instance by using the Node.js SDK, use the serviceUrl parameter. You can copy your endpoint URL from the Endpoints page in the Secrets Manager service dashboard.

If you copy the endpoint URL from your Secrets Manager service dashboard, be sure to add /api to the URL to use it with the SDK.

Endpoint URLs by location

  • Dallas: https://{instance_ID}.us-south.secrets-manager.appdomain.cloud
  • Frankfurt: https://{instance_ID}.eu-de.secrets-manager.appdomain.cloud
  • London: https://{instance_ID}.eu-gb.secrets-manager.appdomain.cloud
  • Osaka: https://{instance_ID}.jp-osa.secrets-manager.appdomain.cloud
  • Sao Paulo: https://{instance_ID}.br-sao.secrets-manager.appdomain.cloud
  • Sydney: https://{instance_ID}.au-syd.secrets-manager.appdomain.cloud
  • Tokyo: https://{instance_ID}.jp-tok.secrets-manager.appdomain.cloud
  • Toronto: https://{instance_ID}.ca-tor.secrets-manager.appdomain.cloud
  • Washington DC: https://{instance_ID}.us-east.secrets-manager.appdomain.cloud

Secrets Manager supports instance-specific endpoint URLs that you can use to interact with the service over public or private service endpoints. To target your Secrets Manager service instance by using the Python SDK, use the set_service_url() method. You can copy your endpoint URL from the Endpoints page in the Secrets Manager service dashboard.

If you copy the endpoint URL from your Secrets Manager service dashboard, be sure to add /api to the URL to use it with the SDK.

Endpoint URLs by location

  • Dallas: https://{instance_ID}.us-south.secrets-manager.appdomain.cloud
  • Frankfurt: https://{instance_ID}.eu-de.secrets-manager.appdomain.cloud
  • London: https://{instance_ID}.eu-gb.secrets-manager.appdomain.cloud
  • Osaka: https://{instance_ID}.jp-osa.secrets-manager.appdomain.cloud
  • Sao Paulo: https://{instance_ID}.br-sao.secrets-manager.appdomain.cloud
  • Sydney: https://{instance_ID}.au-syd.secrets-manager.appdomain.cloud
  • Tokyo: https://{instance_ID}.jp-tok.secrets-manager.appdomain.cloud
  • Toronto: https://{instance_ID}.ca-tor.secrets-manager.appdomain.cloud
  • Washington DC: https://{instance_ID}.us-east.secrets-manager.appdomain.cloud

Secrets Manager supports instance-specific endpoint URLs that you can use to interact with the service over public or private service endpoints. To target your Secrets Manager service instance by using the Go SDK, use the URL parameter. You can copy your endpoint URL from the Endpoints page in the Secrets Manager service dashboard.

If you copy the endpoint URL from your Secrets Manager service dashboard, be sure to add /api to the URL to use it with the SDK.

Endpoint URLs by location

  • Dallas: https://{instance_ID}.us-south.secrets-manager.appdomain.cloud
  • Frankfurt: https://{instance_ID}.eu-de.secrets-manager.appdomain.cloud
  • London: https://{instance_ID}.eu-gb.secrets-manager.appdomain.cloud
  • Osaka: https://{instance_ID}.jp-osa.secrets-manager.appdomain.cloud
  • Sao Paulo: https://{instance_ID}.br-sao.secrets-manager.appdomain.cloud
  • Sydney: https://{instance_ID}.au-syd.secrets-manager.appdomain.cloud
  • Tokyo: https://{instance_ID}.jp-tok.secrets-manager.appdomain.cloud
  • Toronto: https://{instance_ID}.ca-tor.secrets-manager.appdomain.cloud
  • Washington DC: https://{instance_ID}.us-east.secrets-manager.appdomain.cloud

Base URL

https://{instance_ID}.{region}.secrets-manager.appdomain.cloud

Example for the Dallas location

import com.ibm.cloud.secrets_manager_sdk.secrets_manager.v2.SecretsManager;
import com.ibm.cloud.secrets_manager_sdk.secrets_manager.v2.model.*;
import com.ibm.cloud.sdk.core.http.Response;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

import java.util.Collections;
...

// Create an IAM authenticator
IamAuthenticator iamAuthenticator = new IamAuthenticator.Builder()
        .apikey("<API_KEY>")
        .build();

// Construct the service client
SecretsManager secretsManagerService = new SecretsManager("My Secrets-Manager service", iamAuthenticator);

// Set the service URL
secretsManagerService.setServiceUrl("https://{instance_ID}.us-south.secrets-manager.appdomain.cloud/api");

Example for the Dallas location

const IbmCloudSecretsManagerApiV1 =  require('@ibm-cloud/secrets-manager/secrets-manager/v2');
const { IamAuthenticator } = require('@ibm-cloud/secrets-manager/auth');

const secretsManagerService = new SecretsManagerV2({
  authenticator: new IamAuthenticator({
    apikey: '<API_KEY>',
  }),
  serviceUrl: 'https://{instance_ID}.us-south.secrets-manager.appdomain.cloud/api',
});

Example for the Dallas location

from ibm_cloud_sdk_core.authenticators.iam_authenticator import IAMAuthenticator
from ibm_secrets_manager_sdk.secrets_manager_v2 import *

secrets_manager_service = SecretsManagerV2(
    authenticator=IAMAuthenticator(apikey='<API_KEY>')
)

secrets_manager_service.set_service_url('https://{instance_ID}.us-south.secrets-manager.appdomain.cloud/api')

Example for the Dallas location

import (
    "encoding/json"
    "fmt"
    "github.com/IBM/go-sdk-core/v5/core"
    sm "github.com/IBM/secrets-manager-go-sdk/secretsmanagerv2"
)

func main() {

    secretsManagerService, err := sm.NewSecretsManagerV2(&sm.SecretsManagerV2Options {
        URL: "https://{instance_ID}.us-south.secrets-manager.appdomain.cloud/api",
        Authenticator: & core.IamAuthenticator {
            ApiKey: "<API_KEY>",
        },
    })

    if err != nil {
        panic(err)
    }
}

Authentication

Authorization to the Secrets Manager API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

To work with the API, include a valid IAM token in each outgoing request to the service. You can generate an access token by first creating an API key and then exchanging your API key for an IBM Cloud IAM token.

Don't have an API key? Try running ibmcloud iam oauth-tokens in the IBM Cloud Shell to quickly generate a personal access token.

To generate an access token from your API key, use the following cURL command.

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IBM Cloud API key.

When you use the SDK, configure an IAM authenticator with an IBM Cloud IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can configure an authenticator in either of two ways:

  • Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
  • By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

Example API request

curl -X {request_method} "{base_url}/api/v2/{method_endpoint}" --header "Authorization: Bearer {IAM_token}"

Replace {IAM_token} with your access token.

Constructing the service client

import com.ibm.cloud.secrets_manager_sdk.secrets_manager.v2.SecretsManager;
import com.ibm.cloud.secrets_manager_sdk.secrets_manager.v2.model.*;
import com.ibm.cloud.sdk.core.http.Response;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

import java.util.Collections;
...

// Create an IAM authenticator
IamAuthenticator iamAuthenticator = new IamAuthenticator.Builder()
        .apikey("<API_KEY>")
        .build();

// Construct the service client
SecretsManager secretsManagerService = new SecretsManager("My Secrets-Manager service", iamAuthenticator);

// Set the service URL
secretsManagerService.setServiceUrl("<URL>");

Replace <API_KEY> with your IBM Cloud API key. Replace <URL> with the endpoint URL for your instance. Invoke service operations by using the secretsManagerService variable.

Constructing the service client

from ibm_cloud_sdk_core.authenticators.iam_authenticator import IAMAuthenticator
from ibm_secrets_manager_sdk.secrets_manager_v2 import *

secrets_manager_service = SecretsManagerV2(
    authenticator=IAMAuthenticator(apikey='<API_KEY>')
)

secrets_manager_service.set_service_url('<URL>')

Replace <API_KEY> with your IBM Cloud API key. Replace <URL> with the endpoint URL for your instance.

Constructing the service client

import (
    "encoding/json"
    "fmt"
    "github.com/IBM/go-sdk-core/v5/core"
    sm "github.com/IBM/secrets-manager-go-sdk/secretsmanagerv2"
)

func main() {

    secretsManagerService, err := sm.NewSecretsManagerV2(&sm.SecretsManagerV2Options {
        URL: "<URL>",
        Authenticator: & core.IamAuthenticator {
            ApiKey: "<API_KEY>",
        },
    })

    if err != nil {
        panic(err)
    }
}

Replace <API_KEY> with your IBM Cloud API key. Replace <URL> with the endpoint URL for your instance.

Constructing the service client

const IbmCloudSecretsManagerApiV2 =  require('@ibm-cloud/secrets-manager/secrets-manager/v2');
const { IamAuthenticator } = require('@ibm-cloud/secrets-manager/auth');

const secretsManagerService = new IbmCloudSecretsManagerApiV2({
  authenticator: new IamAuthenticator({
    apikey: '<API_KEY>',
  }),
  serviceUrl: '<URL>',
});

Replace <API_KEY> with your IBM Cloud API key. Replace <URL> with the endpoint URL for your instance.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track Secrets Manager activity, see Auditing events for Secrets Manager.

Error handling

The Secrets Manager APIs use standard HTTP status codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error.

Status code summary
Status code Description
200 OK Everything worked as expected.
300 Multiple Choices The request has more than one possible responses.
400 Bad Request The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized The parameters were valid but the request failed due insufficient permissions.
402 Payment Required Your Trial plan is now expired.
403 Forbidden You are not allowed to access this resource.
404 Not Found The requested resource doesn't exist.
409 Conflict The requested resource conflicts with an already existing resource.
410 Gone The requested resource was deleted and no longer exists.
429 Too Many Requests Too many requests hit the API too quickly.
500 Internal Server Error Something went wrong on Secrets Manager's end.

Example error handling

secretsManagerApi.method(params)
  .catch(err => {
    console.log('Error:', err);
  });

Example error handling

import "github.com/IBM/secrets-manager-go-sdk/ibm-cloud-secrets-manager-api-v1"

// Instantiate a service
secretsManagerApi, err := sm.NewIbmCloudSecretsManagerV1(options)

// Check for errors
if err != nil {
  panic(err)
}

// Call a method
result, response, err := secretsManagerApi.MethodName(&methodOptions)

// Check for errors
if err != nil {
  panic(err)
}

Pagination

Some API requests might return a large number of results. To avoid performance issues, the Secrets Manager API returns one page of results at a time, with a limited number of results on each page.

The default page size is defined differently for each operation. To use a different page size, use the limit query parameter.

Rate limiting

Secrets Manager API does not enforce a hard rate-limit. However as requests rate increase, some performance degradation is expected. The impact depends on the requests patterns. As a rule of thumb it is recommended to keep the rate below 20 requests per second.

Change log

For the latest changes, improvements, and updates for this API, see the API change log.

Methods

Create a new secret group

Create a secret group that you can use to organize secrets and control who can access them.

A successful request returns the ID value of the secret group, along with other properties. To learn more about secret groups, check out the docs.

Create a secret group that you can use to organize secrets and control who can access them.

A successful request returns the ID value of the secret group, along with other properties. To learn more about secret groups, check out the docs.

Create a secret group that you can use to organize secrets and control who can access them.

A successful request returns the ID value of the secret group, along with other properties. To learn more about secret groups, check out the docs.

Create a secret group that you can use to organize secrets and control who can access them.

A successful request returns the ID value of the secret group, along with other properties. To learn more about secret groups, check out the docs.

Create a secret group that you can use to organize secrets and control who can access them.

A successful request returns the ID value of the secret group, along with other properties. To learn more about secret groups, check out the docs.

POST /api/v2/secret_groups
ServiceCall<SecretGroup> createSecretGroup(CreateSecretGroupOptions createSecretGroupOptions)
createSecretGroup(params)
create_secret_group(
        self,
        name: str,
        *,
        description: str = None,
        **kwargs,
    ) -> DetailedResponse
(secretsManager *SecretsManagerV2) CreateSecretGroup(createSecretGroupOptions *CreateSecretGroupOptions) (result *SecretGroup, response *core.DetailedResponse, err error)
(secretsManager *SecretsManagerV2) CreateSecretGroupWithContext(ctx context.Context, createSecretGroupOptions *CreateSecretGroupOptions) (result *SecretGroup, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • secrets-manager.secret-group.create

Auditing

Calling this method generates the following auditing event.

  • secrets-manager.secret-group.create

Request

Use the CreateSecretGroupOptions.Builder to create a CreateSecretGroupOptions object that contains the parameter values for the createSecretGroup method.

Instantiate the CreateSecretGroupOptions struct and set the fields to provide parameter values for the CreateSecretGroup method.

Request Body

Required*
SecretGroupPrototype

The request body to create a new secret group.

Examples:
View

CreateSecretGroupOptions

The createSecretGroup options.

parameters

  • name
    Required*
    string

    The name of your secret group.

    Possible values: 2 ≤ length ≤ 64, Value must match regular expression /^[A-Za-z0-9_][A-Za-z0-9_]*(?:_*-*\\.*[A-Za-z0-9]*)*[A-Za-z0-9]+$/

    Examples:
    value
    _source
    _lines
    _html
  • description
    string

    An extended description of your secret group.

    To protect your privacy, do not use personal data, such as your name or location, as a description for your secret group.

    Possible values: 0 ≤ length ≤ 1024, Value must match regular expression /(.*?)/

    Examples:
    value
    _source
    _lines
    _html

parameters

  • name
    Required*
    str

    The name of your secret group.

    Possible values: 2 ≤ length ≤ 64, Value must match regular expression /^[A-Za-z0-9_][A-Za-z0-9_]*(?:_*-*\\.*[A-Za-z0-9]*)*[A-Za-z0-9]+$/

    Examples:
    value
    _source
    _lines
    _html
  • description
    str

    An extended description of your secret group.

    To protect your privacy, do not use personal data, such as your name or location, as a description for your secret group.

    Possible values: 0 ≤ length ≤ 1024, Value must match regular expression /(.*?)/

    Examples:
    value
    _source
    _lines
    _html

parameter

WithContext method only

CreateSecretGroupOptions

The CreateSecretGroup options.

  • curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{"name":"my-secret-group","description":"Extended description for this group."}'   "{base_url}/api/v2/secret_groups"
  • CreateSecretGroupOptions createSecretGroupOptions = new CreateSecretGroupOptions.Builder()
  .name("my-secret-group")
  .build();

Response<SecretGroup> response = secretsManagerService.createSecretGroup(createSecretGroupOptions).execute();
SecretGroup secretGroup = response.getResult();

System.out.println(secretGroup);
  • const params = {
  name: 'my-secret-group',
};

let res;
try {
  res = await secretsManagerService.createSecretGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
  • response = secrets_manager_service.create_secret_group(
  name='my-secret-group',
)
secret_group = response.get_result()

print(json.dumps(secret_group, indent=2))
  • createSecretGroupOptions := secretsManagerService.NewCreateSecretGroupOptions(
  "my-secret-group",
)

secretGroup, response, err := secretsManagerService.CreateSecretGroup(createSecretGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(secretGroup, "", "  ")
fmt.Println(string(b))

Response

Response Body

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

Status Code

  • 201

    The secret group was successfully created.

  • 400

    BadRequest

  • 401

    Unauthorized

  • 402

    PaymentRequired

  • 403

    Forbidden

  • 404

    The specified resource was not found

  • 500

    InternalServerError

  • 503

    ServiceUnavailableError

Example responses

  • Example of SecretGroup response

    {
  "created_at": "2020-10-05T21:33:11Z",
  "description": "Extended description for this group.",
  "id": "d898bb90-82f6-4d61-b5cc-b079b66cfa76",
  "name": "my-secret-group",
  "updated_at": "2020-11-25T22:13:10Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
}

  • Example of SecretGroup response

    {
  "created_at": "2020-10-05T21:33:11Z",
  "description": "Extended description for this group.",
  "id": "d898bb90-82f6-4d61-b5cc-b079b66cfa76",
  "name": "my-secret-group",
  "updated_at": "2020-11-25T22:13:10Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

List secret groups

List the secret groups that are available in your Secrets Manager instance.

List the secret groups that are available in your Secrets Manager instance.

List the secret groups that are available in your Secrets Manager instance.

List the secret groups that are available in your Secrets Manager instance.

List the secret groups that are available in your Secrets Manager instance.

GET /api/v2/secret_groups
ServiceCall<SecretGroupCollection> listSecretGroups()
listSecretGroups(params)
list_secret_groups(
        self,
        **kwargs,
    ) -> DetailedResponse
(secretsManager *SecretsManagerV2) ListSecretGroups(listSecretGroupsOptions *ListSecretGroupsOptions) (result *SecretGroupCollection, response *core.DetailedResponse, err error)
(secretsManager *SecretsManagerV2) ListSecretGroupsWithContext(ctx context.Context, listSecretGroupsOptions *ListSecretGroupsOptions) (result *SecretGroupCollection, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • secrets-manager.secret-groups.list

Auditing

Calling this method generates the following auditing event.

  • secrets-manager.secret-groups.list

Request

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

parameter

WithContext method only

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/api/v2/secret_groups"
  • ListSecretGroupsOptions listSecretGroupsOptions = new ListSecretGroupsOptions();

Response<SecretGroupCollection> response = secretsManagerService.listSecretGroups(listSecretGroupsOptions).execute();
SecretGroupCollection secretGroupCollection = response.getResult();

System.out.println(secretGroupCollection);
  • let res;
try {
  res = await secretsManagerService.listSecretGroups({});
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
  • response = secrets_manager_service.list_secret_groups()
secret_group_collection = response.get_result()

print(json.dumps(secret_group_collection, indent=2))
  • listSecretGroupsOptions := secretsManagerService.NewListSecretGroupsOptions()

secretGroupCollection, response, err := secretsManagerService.ListSecretGroups(listSecretGroupsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(secretGroupCollection, "", "  ")
fmt.Println(string(b))

Response

Response Body

SecretGroupCollection

Properties that describe a collection of secret groups.

SecretGroupCollection

Properties that describe a collection of secret groups.

SecretGroupCollection

Properties that describe a collection of secret groups.

SecretGroupCollection

Properties that describe a collection of secret groups.

SecretGroupCollection

Properties that describe a collection of secret groups.

Status Code

  • 200

    The list of secret groups was successfully retrieved.

  • 400

    BadRequest

  • 401

    Unauthorized

  • 402

    PaymentRequired

  • 403

    Forbidden

  • 404

    The specified resource was not found

  • 500

    InternalServerError

  • 503

    ServiceUnavailableError

Example responses

  • Example SecretGroup collection response

    {
  "secret_groups": [
    {
      "created_at": "2020-09-05T21:33:11Z",
      "description": "Default Secret Group",
      "id": "ee52ebb6-1728-4580-8ede-13f6504e3ae0",
      "name": "default",
      "updated_at": "2020-09-25T22:13:10Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
    },
    {
      "created_at": "2020-10-05T21:33:11Z",
      "description": "Extended description for this group.",
      "id": "cb52ebb6-1728-4580-8ede-13f6504e3ae0",
      "name": "my-secret-group",
      "updated_at": "2020-11-25T22:13:10Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
    },
    {
      "created_at": "2020-10-05T22:05:15Z",
      "description": "Extended description for this group.",
      "id": "19f88b9c-4f2f-405c-b877-a09338575c3f",
      "name": "my-second-secret-group",
      "updated_at": "2020-11-25T22:13:10Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
    }
  ],
  "total_count": 3
}

  • Example SecretGroup collection response

    {
  "secret_groups": [
    {
      "created_at": "2020-09-05T21:33:11Z",
      "description": "Default Secret Group",
      "id": "ee52ebb6-1728-4580-8ede-13f6504e3ae0",
      "name": "default",
      "updated_at": "2020-09-25T22:13:10Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
    },
    {
      "created_at": "2020-10-05T21:33:11Z",
      "description": "Extended description for this group.",
      "id": "cb52ebb6-1728-4580-8ede-13f6504e3ae0",
      "name": "my-secret-group",
      "updated_at": "2020-11-25T22:13:10Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
    },
    {
      "created_at": "2020-10-05T22:05:15Z",
      "description": "Extended description for this group.",
      "id": "19f88b9c-4f2f-405c-b877-a09338575c3f",
      "name": "my-second-secret-group",
      "updated_at": "2020-11-25T22:13:10Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
    }
  ],
  "total_count": 3
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

Get a secret group

Get the properties of an existing secret group by specifying the ID of the group.

Get the properties of an existing secret group by specifying the ID of the group.

Get the properties of an existing secret group by specifying the ID of the group.

Get the properties of an existing secret group by specifying the ID of the group.

Get the properties of an existing secret group by specifying the ID of the group.

GET /api/v2/secret_groups/{id}
ServiceCall<SecretGroup> getSecretGroup(GetSecretGroupOptions getSecretGroupOptions)
getSecretGroup(params)
get_secret_group(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse
(secretsManager *SecretsManagerV2) GetSecretGroup(getSecretGroupOptions *GetSecretGroupOptions) (result *SecretGroup, response *core.DetailedResponse, err error)
(secretsManager *SecretsManagerV2) GetSecretGroupWithContext(ctx context.Context, getSecretGroupOptions *GetSecretGroupOptions) (result *SecretGroup, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • secrets-manager.secret-group.read

Auditing

Calling this method generates the following auditing event.

  • secrets-manager.secret-group.read

Request

Use the GetSecretGroupOptions.Builder to create a GetSecretGroupOptions object that contains the parameter values for the getSecretGroup method.

Instantiate the GetSecretGroupOptions struct and set the fields to provide parameter values for the GetSecretGroup method.

Path Parameters

  • id
    Required*
    string

    The v4 UUID that uniquely identifies your secret group.

    Possible values: 7 ≤ length ≤ 36, Value must match regular expression ^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|default)$

    Example: d898bb90-82f6-4d61-b5cc-b079b66cfa76

GetSecretGroupOptions

The getSecretGroup options.

parameters

  • id
    Required*
    string

    The v4 UUID that uniquely identifies your secret group.

    Possible values: 7 ≤ length ≤ 36, Value must match regular expression /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|default)$/

    Examples:
    value
    _source
    _lines
    _html

parameters

  • id
    Required*
    str

    The v4 UUID that uniquely identifies your secret group.

    Possible values: 7 ≤ length ≤ 36, Value must match regular expression /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|default)$/

    Examples:
    value
    _source
    _lines
    _html

parameter

WithContext method only

GetSecretGroupOptions

The GetSecretGroup options.

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/api/v2/secret_groups/{id}"
  • GetSecretGroupOptions getSecretGroupOptions = new GetSecretGroupOptions.Builder()
  .id(secretGroupIdForGetSecretGroupLink)
  .build();

Response<SecretGroup> response = secretsManagerService.getSecretGroup(getSecretGroupOptions).execute();
SecretGroup secretGroup = response.getResult();

System.out.println(secretGroup);
  • const params = {
  id: secretGroupIdForGetSecretGroupLink,
};

let res;
try {
  res = await secretsManagerService.getSecretGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
  • response = secrets_manager_service.get_secret_group(
  id=secret_group_id_for_get_secret_group_link,
)
secret_group = response.get_result()

print(json.dumps(secret_group, indent=2))
  • getSecretGroupOptions := secretsManagerService.NewGetSecretGroupOptions(
  secretGroupIdForGetSecretGroupLink,
)

secretGroup, response, err := secretsManagerService.GetSecretGroup(getSecretGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(secretGroup, "", "  ")
fmt.Println(string(b))

Response

Response Body

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

Status Code

  • 200

    The secret group was successfully retrieved.

  • 400

    BadRequest

  • 401

    Unauthorized

  • 402

    PaymentRequired

  • 403

    Forbidden

  • 404

    The specified resource was not found

  • 500

    InternalServerError

  • 503

    ServiceUnavailableError

Example responses

  • Example of SecretGroup response

    {
  "created_at": "2020-10-05T21:33:11Z",
  "description": "Extended description for this group.",
  "id": "d898bb90-82f6-4d61-b5cc-b079b66cfa76",
  "name": "my-secret-group",
  "updated_at": "2020-11-25T22:13:10Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
}

  • Example of SecretGroup response

    {
  "created_at": "2020-10-05T21:33:11Z",
  "description": "Extended description for this group.",
  "id": "d898bb90-82f6-4d61-b5cc-b079b66cfa76",
  "name": "my-secret-group",
  "updated_at": "2020-11-25T22:13:10Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

Update a secret group

Update the properties of an existing secret group, such as its name or description.

Update the properties of an existing secret group, such as its name or description.

Update the properties of an existing secret group, such as its name or description.

Update the properties of an existing secret group, such as its name or description.

Update the properties of an existing secret group, such as its name or description.

PATCH /api/v2/secret_groups/{id}
ServiceCall<SecretGroup> updateSecretGroup(UpdateSecretGroupOptions updateSecretGroupOptions)
updateSecretGroup(params)
update_secret_group(
        self,
        id: str,
        secret_group_patch: 'SecretGroupPatch',
        **kwargs,
    ) -> DetailedResponse
(secretsManager *SecretsManagerV2) UpdateSecretGroup(updateSecretGroupOptions *UpdateSecretGroupOptions) (result *SecretGroup, response *core.DetailedResponse, err error)
(secretsManager *SecretsManagerV2) UpdateSecretGroupWithContext(ctx context.Context, updateSecretGroupOptions *UpdateSecretGroupOptions) (result *SecretGroup, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • secrets-manager.secret-group.update

Auditing

Calling this method generates the following auditing event.

  • secrets-manager.secret-group.update

Request

Use the UpdateSecretGroupOptions.Builder to create a UpdateSecretGroupOptions object that contains the parameter values for the updateSecretGroup method.

Instantiate the UpdateSecretGroupOptions struct and set the fields to provide parameter values for the UpdateSecretGroup method.

Path Parameters

  • id
    Required*
    string

    The v4 UUID that uniquely identifies your secret group.

    Possible values: length = 36, Value must match regular expression [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

    Example: d898bb90-82f6-4d61-b5cc-b079b66cfa76

Request Body

Required*
application/merge-patch+jsonSecretGroupPatch

The request body to update a secret group.

Examples:
View

UpdateSecretGroupOptions

The updateSecretGroup options.

parameters

  • id
    Required*
    string

    The v4 UUID that uniquely identifies your secret group.

    Possible values: length = 36, Value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/

    Examples:
    value
    _source
    _lines
    _html
  • name
    string

    The name of your secret group.

    Possible values: 2 ≤ length ≤ 64, Value must match regular expression /^[A-Za-z0-9_][A-Za-z0-9_]*(?:_*-*\\.*[A-Za-z0-9]*)*[A-Za-z0-9]+$/

    Examples:
    value
    _source
    _lines
    _html
  • description
    string

    An extended description of your secret group.

    To protect your privacy, do not use personal data, such as your name or location, as a description for your secret group.

    Possible values: 0 ≤ length ≤ 1024, Value must match regular expression /(.*?)/

    Examples:
    value
    _source
    _lines
    _html

parameters

  • id
    Required*
    str

    The v4 UUID that uniquely identifies your secret group.

    Possible values: length = 36, Value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/

    Examples:
    value
    _source
    _lines
    _html
  • secret_group_patch

    Update the name or description of your secret group.

    Examples:
    View

parameter

WithContext method only

UpdateSecretGroupOptions

The UpdateSecretGroup options.

  • curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/merge-patch+json"   --data ''   "{base_url}/api/v2/secret_groups/{id}"
  • SecretGroupPatch secretGroupPatchModel = new SecretGroupPatch.Builder()
  .build();
Map<String, Object> secretGroupPatchModelAsPatch = secretGroupPatchModel.asPatch();
UpdateSecretGroupOptions updateSecretGroupOptions = new UpdateSecretGroupOptions.Builder()
  .id(secretGroupIdForGetSecretGroupLink)
  .secretGroupPatch(secretGroupPatchModelAsPatch)
  .build();

Response<SecretGroup> response = secretsManagerService.updateSecretGroup(updateSecretGroupOptions).execute();
SecretGroup secretGroup = response.getResult();

System.out.println(secretGroup);
  • const params = {
  id: secretGroupIdForGetSecretGroupLink,
};

let res;
try {
  res = await secretsManagerService.updateSecretGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
  • secret_group_patch_model = {
}

response = secrets_manager_service.update_secret_group(
  id=secret_group_id_for_get_secret_group_link,
  secret_group_patch=secret_group_patch_model,
)
secret_group = response.get_result()

print(json.dumps(secret_group, indent=2))
  • secretGroupPatchModel := &secretsmanagerv2.SecretGroupPatch{
}
secretGroupPatchModelAsPatch, asPatchErr := secretGroupPatchModel.AsPatch()
Expect(asPatchErr).To(BeNil())

updateSecretGroupOptions := secretsManagerService.NewUpdateSecretGroupOptions(
  secretGroupIdForGetSecretGroupLink,
  secretGroupPatchModelAsPatch,
)

secretGroup, response, err := secretsManagerService.UpdateSecretGroup(updateSecretGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(secretGroup, "", "  ")
fmt.Println(string(b))

Response

Response Body

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

SecretGroup

Properties that describe a secret group.

Status Code

  • 200

    The secret group was successfully updated.

  • 400

    BadRequest

  • 401

    Unauthorized

  • 402

    PaymentRequired

  • 403

    Forbidden

  • 404

    The specified resource was not found

  • 500

    InternalServerError

  • 503

    ServiceUnavailableError

Example responses

  • Example of SecretGroup response

    {
  "created_at": "2020-10-05T21:33:11Z",
  "description": "Extended description for this group.",
  "id": "d898bb90-82f6-4d61-b5cc-b079b66cfa76",
  "name": "my-secret-group",
  "updated_at": "2020-11-25T22:13:10Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
}

  • Example of SecretGroup response

    {
  "created_at": "2020-10-05T21:33:11Z",
  "description": "Extended description for this group.",
  "id": "d898bb90-82f6-4d61-b5cc-b079b66cfa76",
  "name": "my-secret-group",
  "updated_at": "2020-11-25T22:13:10Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21"
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

Delete a secret group

Delete a secret group by specifying the ID of the secret group.

Note: 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 that are associated with the group.

Delete a secret group by specifying the ID of the secret group.

Note: 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 that are associated with the group.

Delete a secret group by specifying the ID of the secret group.

Note: 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 that are associated with the group.

Delete a secret group by specifying the ID of the secret group.

Note: 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 that are associated with the group.

Delete a secret group by specifying the ID of the secret group.

Note: 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 that are associated with the group.

DELETE /api/v2/secret_groups/{id}
ServiceCall<Void> deleteSecretGroup(DeleteSecretGroupOptions deleteSecretGroupOptions)
deleteSecretGroup(params)
delete_secret_group(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse
(secretsManager *SecretsManagerV2) DeleteSecretGroup(deleteSecretGroupOptions *DeleteSecretGroupOptions) (response *core.DetailedResponse, err error)
(secretsManager *SecretsManagerV2) DeleteSecretGroupWithContext(ctx context.Context, deleteSecretGroupOptions *DeleteSecretGroupOptions) (response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • secrets-manager.secret-group.delete

Auditing

Calling this method generates the following auditing event.

  • secrets-manager.secret-group.delete

Request

Use the DeleteSecretGroupOptions.Builder to create a DeleteSecretGroupOptions object that contains the parameter values for the deleteSecretGroup method.

Instantiate the DeleteSecretGroupOptions struct and set the fields to provide parameter values for the DeleteSecretGroup method.

Path Parameters

  • id
    Required*
    string

    The v4 UUID that uniquely identifies your secret group.

    Possible values: length = 36, Value must match regular expression [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

    Example: d898bb90-82f6-4d61-b5cc-b079b66cfa76

DeleteSecretGroupOptions

The deleteSecretGroup options.

parameters

  • id
    Required*
    string

    The v4 UUID that uniquely identifies your secret group.

    Possible values: length = 36, Value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/

    Examples:
    value
    _source
    _lines
    _html

parameters

  • id
    Required*
    str

    The v4 UUID that uniquely identifies your secret group.

    Possible values: length = 36, Value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/

    Examples:
    value
    _source
    _lines
    _html

parameter

WithContext method only

DeleteSecretGroupOptions

The DeleteSecretGroup options.

  • curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/api/v2/secret_groups/{id}"
  • DeleteSecretGroupOptions deleteSecretGroupOptions = new DeleteSecretGroupOptions.Builder()
  .id(secretGroupIdForGetSecretGroupLink)
  .build();

Response<Void> response = secretsManagerService.deleteSecretGroup(deleteSecretGroupOptions).execute();
  • const params = {
  id: secretGroupIdForGetSecretGroupLink,
};

try {
  await secretsManagerService.deleteSecretGroup(params);
} catch (err) {
  console.warn(err);
}
  • response = secrets_manager_service.delete_secret_group(
  id=secret_group_id_for_get_secret_group_link,
)
  • deleteSecretGroupOptions := secretsManagerService.NewDeleteSecretGroupOptions(
  secretGroupIdForGetSecretGroupLink,
)

response, err := secretsManagerService.DeleteSecretGroup(deleteSecretGroupOptions)
if err != nil {
  panic(err)
}
if response.StatusCode != 204 {
  fmt.Printf("\nUnexpected response status code received from DeleteSecretGroup(): %d\n", response.StatusCode)
}

Response

Status Code

  • 204

    The secret group was successfully deleted.

  • 400

    BadRequest

  • 401

    Unauthorized

  • 402

    PaymentRequired

  • 403

    Forbidden

  • 404

    The specified resource was not found

  • 409

    Conflict

  • 500

    InternalServerError

  • 503

    ServiceUnavailableError

Example responses

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of bad request error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 400,
  "errors": [
    {
      "code": "bad_request",
      "message": "required.name:property \"name\" is missing",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of unauthorized error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "You provided no credentials or invalid credentials.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of payment required error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 402,
  "errors": [
    {
      "code": "payment_required",
      "message": "Your Trial plan is now expired.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of forbidden error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 403,
  "errors": [
    {
      "code": "access_forbidden",
      "message": "You are not allowed to access this resource.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of NotFound error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "A resource with id: 19f88b9c-4f2f-405c-b877-a09338575c3f was not found.",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example Conflict error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 409,
  "errors": [
    {
      "code": "conflict",
      "message": "The request conflicts with the current state of the target resource",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example Conflict error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 409,
  "errors": [
    {
      "code": "conflict",
      "message": "The request conflicts with the current state of the target resource",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of internal server error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 500,
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

  • Example of service unavailable error

    {
  "trace": "f9d9d161-e087-4871-963b-88ea3fe72aca",
  "status_code": 503,
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Unavailable",
      "more_info": "https://cloud.ibm.com/apidocs/secrets-manager"
    }
  ]
}

Create a new secret

Create a secret or import an existing value that you can use to access or authenticate to a protected resource.

Use this operation to either generate or import an existing secret, such as a TLS certificate, that you can manage in your Secrets Manager service instance. A successful request stores the secret in your dedicated instance, based on the secret type and data that you specify. The response returns the ID value of the secret, along with other metadata.

To learn more about the types of secrets that you can create with Secrets Manager, check out the docs.