Instance management API reference

Use the IBM Cloud Secrets Manager instance management API to manage service instances of the Vault Dedicated plan. For Vault runtime operations such as secrets management, authentication methods, and policies, use the HashiCorp Vault API.

For the interactive API reference with SDK examples, see the Instance Management API reference.

IBM Cloud Secrets Manager Instance Management API

The IBM Cloud Secrets Manager instance management API provides control plane operations for managing your Vault Dedicated service instances. These APIs allow you to retrieve instance metadata, manage admin tokens, and configure instance settings.

Authentication

All API requests require authentication using an IBM Cloud IAM token. Include your IAM token in the Authorization header of each request:

Authorization: Bearer {iam_token}

For information on generating IAM tokens, see Creating an IAM access token for a user or service ID.

Base URL

The base URL for the Instance Management API is the control plane service endpoint for your instance. You can find this endpoint in the Endpoints page of your Secrets Manager service dashboard.

https://{region}.secrets-manager.cloud.ibm.com

Replace {region} with the region where your instance is deployed (for example, us-south, eu-de).

Getting instance details

Use the instance details API to retrieve metadata about your Vault Dedicated service instance, including cluster state, endpoints, and key management service configuration.

Getting instance details in the UI

  1. In the IBM Cloud console, click the Menu icon Menu icon > Resource List.
  2. From the list of services, select your Vault Dedicated instance.
  3. In the instance dashboard, review the Endpoints section to find the cluster state, Vault API endpoint, and other instance details.

Getting instance details from the CLI

To retrieve the details of your Vault Dedicated instance by using the IBM Cloud CLI, run the following command.

ibmcloud secrets-manager-instance-management instance-details --id {instance_id}

Getting instance details with the API

Retrieve detailed information about your Vault Dedicated instance.

Request

GET /v2/instances/{id}

Example request

curl -X GET \
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: application/json" \
  "https://{region}.secrets-manager.cloud.ibm.com/v2/instances/{id}"

Response

The response includes the following information:

  • id: The instance ID (UUID)
  • name: The instance name
  • instance_crn: The instance CRN identifier
  • plan: The instance plan name (dedicated)
  • vault_cluster: Vault cluster information, including status (healthy, sealed, or not_initialized) and version
  • endpoints: Public and private endpoint URLs, each containing vault_api and vault_ui fields
  • encryption: Key management service configuration, including mode (service_managed or customer_managed), and optionally provider and key_crn for customer-managed encryption

Example response

{
  "id": "bfc50c2e-d66d-4f37-9ccf-9713f8325b39",
  "name": "my-vault-dedicated-instance",
  "instance_crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/...:bfc50c2e-d66d-4f37-9ccf-9713f8325b39::",
  "plan": "dedicated",
  "vault_cluster": {
    "status": "healthy",
    "version": "2.0.4"
  },
  "endpoints": {
    "public": {
      "vault_api": "https://bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud",
      "vault_ui": "https://bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud/ui"
    },
    "private": {
      "vault_api": "https://private.bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud",
      "vault_ui": "https://private.bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud/ui"
    }
  },
  "encryption": {
    "mode": "service_managed"
  },
  "href": "https://us-south.secrets-manager.cloud.ibm.com/v2/instances/bfc50c2e-d66d-4f37-9ccf-9713f8325b39"
}

Getting instance details with Terraform

To get the details of a Vault Dedicated instance with Terraform, use the ibm_sm_instance data source.

data "ibm_sm_instance" "sm_instance" {
  instance_id = "bfc50c2e-d66d-4f37-9ccf-9713f8325b39"
}

After your data source is created, you can reference its attributes. For example, to get the public Vault API endpoint:

data.ibm_sm_instance.sm_instance.endpoints.0.public.0.vault_api

Managing admin tokens

Admin tokens provide root-level access to your Vault Dedicated cluster and are required for initial setup and administrative operations.

Treat admin tokens as highly sensitive credentials. Generate them only when needed for administrative tasks, and revoke them immediately after use.

Generating an admin token in the UI

  1. In the IBM Cloud console, click the Menu icon Menu icon > Resource List.
  2. From the list of services, select your Vault Dedicated instance.
  3. In the instance dashboard, click Create token in the Create new admin token section.
  4. Copy the generated admin token and store it securely. You need this token to sign in to the Vault UI.

Generating an admin token from the CLI

To generate a new Vault admin token by using the IBM Cloud CLI, run the following command.

ibmcloud secrets-manager-instance-management admin-token-create --id {instance_id}

The command returns the Vault admin token. Store it securely — you need this token to sign in to the Vault UI. The token is valid for 1 hour.

Generating an admin token with the API

Generate a new Vault admin token for authenticating to your Vault Dedicated cluster. This token provides root-level access and should be used only for initial setup and administrative operations. The token is valid for 1 hour.

Request

POST /v2/instances/{id}/admintokens

Example request

curl -X POST \
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: application/json" \
  "https://{region}.secrets-manager.cloud.ibm.com/v2/instances/{id}/admintokens"

Response

A successful request returns HTTP 201 Created with a JSON object containing the Vault admin token.

Example response

{
  "token": "hvs.CAESIJ..."
}

Generating an admin token with Terraform

To generate a Vault admin token with Terraform, use the ibm_sm_admin_token resource. The token is valid for 1 hour, and is automatically refreshed when it is close to expiry.

resource "ibm_sm_admin_token" "sm_admin_token" {
  instance_id = "bfc50c2e-d66d-4f37-9ccf-9713f8325b39"
}

After the resource is created, the token is available in the token attribute.

Using the admin token

Use the vault_api endpoint from the instance details response to authenticate Vault API calls:

curl -X GET \
  -H "X-Vault-Token: hvs.CAESIJ..." \
  "{vault_api_endpoint}/v1/sys/health"

Revoking all admin tokens in the UI

  1. In the IBM Cloud console, click the Menu icon Menu icon > Resource List.
  2. From the list of services, select your Vault Dedicated instance.
  3. In the instance dashboard, click Revoke in the Revoke all admin tokens section.
  4. Confirm the revocation when prompted.

Revoking the token immediately invalidates it and helps reduce the risk of unintended access.

Revoking all admin tokens from the CLI

To revoke all active Vault admin tokens by using the IBM Cloud CLI, run the following command.

ibmcloud secrets-manager-instance-management admin-tokens-delete --id {instance_id}

This operation immediately invalidates all admin tokens, requiring new tokens to be generated for future administrative access.

Revoking all admin tokens with the API

Revoke all active Vault admin tokens for your instance. This operation immediately invalidates all admin tokens, requiring new tokens to be generated for future administrative access.

Request

DELETE /v2/instances/{id}/admintokens

Example request

curl -X DELETE \
  -H "Authorization: Bearer {iam_token}" \
  "https://{region}.secrets-manager.cloud.ibm.com/v2/instances/{id}/admintokens"

Response

A successful revocation returns a 204 No Content status code.

HashiCorp Vault API

For Vault runtime operations such as secrets management, authentication methods, policies, and secrets engines, use the HashiCorp Vault API and CLI documentation.

Next steps