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.

Secrets Manager Instance Management API

The 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 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

Generating an admin token from the CLI

Plain admin token

Generate a plain Vault admin token by using the IBM Cloud CLI.

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

The command returns the Vault admin token. The token is valid for an hour and is non-renewable. Store it securely and revoke it as soon as you no longer need it.

Wrapped admin token (for Vault Web UI login)

Generate a response-wrapped token. For example, to open the Vault Web UI from a script or automated workflow without exposing the real admin token, pass the --response-wrapping flag.

ibmcloud secrets-manager-instance-management admin-token-create \
  --id {instance_id} \
  --response-wrapping true

The command returns a short-lived wrapping token (valid for 30 seconds) instead of the real admin token. To open the Vault Web UI with this token, navigate to the following URL in your browser:

https://{vault_ui_endpoint}/ui/vault/auth?wrapped_token={wrapping_token}

Replace {vault_ui_endpoint} with the vault_ui value from your instance endpoints and {wrapping_token} with the value returned by the command. The Vault UI automatically unwraps the token and establishes an authenticated session. The wrapping token is single-use and expires after 30 seconds.

The Vault session is backed by a 1-hour, non-renewable admin token. The Vault Web UI automatically logs you out when this token expires. To start a new session, generate a new wrapped token and navigate to the URL again.

Generating an admin token with the API

The POST /v2/instances/{id}/admintokens endpoint supports two modes controlled by the optional response_wrapping field in the request body.

Request

POST /v2/instances/{id}/admintokens

Plain admin token

Omit the request body, send an empty object {}, or set response_wrapping to false to receive the plain admin token. The token is valid for an hour and is non-renewable.

Example request

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

Example response

A successful request returns HTTP 201 Created:

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

Wrapped admin token (for Vault Web UI login)

Set response_wrapping to true to receive a response-wrapped token instead of the plain admin token. The wrapping token is single-use and expires after 30 seconds.

Example request

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

Example response

A successful request returns HTTP 201 Created:

{
  "wrapped_token": "hvs.yyy..."
}

To open the Vault Web UI with this token, navigate to the following URL:

https://{vault_ui_endpoint}/ui/vault/auth?wrapped_token={wrapped_token}

The Vault UI automatically calls POST /v1/sys/wrapping/unwrap, exchanges the wrapping token for the real admin token, and establishes an authenticated session. The wrapping token is consumed on first use.

The Vault session is backed by a 1-hour, non-renewable admin token. The Vault Web UI automatically logs you out when this token expires. To start a new session, request a new wrapped token and navigate to the URL again.

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 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