Managing admin tokens

IBM Cloud Vault Dedicated clusters operate from the admin namespace, unlike a self-managed Vault Enterprise cluster which operates from the root namespace. The root namespace is reserved for service operations and not customer accessible.

Admin tokens provide administrative access to your Vault Dedicated cluster admin namespace and are required for initial setup and ongoing administrative operations performed through the CLI, API, or Terraform. When accessing Vault through the IBM Cloud console UI, admin tokens are handled automatically. You can generate and revoke admin tokens through the Secrets Manager Instance Management API.

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

How admin token generation works

Each time you request an admin token, the service creates a non-renewable admin token with a time-to-live (TTL) of 1 hour. The token expires automatically after 1 hour and cannot be renewed.

The admin token provides administrative access to your Vault Dedicated cluster's admin namespace. It can be used to create namespaces, configure secrets engines and authentication methods, manage policies, and perform other administrative tasks. The admin token does not provide access to service-managed operations such as sealing or unsealing Vault, cluster scaling, and storage management, those operations are performed exclusively by the IBM Cloud Vault Dedicated service.

Accessing Vault through the IBM Cloud console

When a user with service Manager role clicks Launch Vault Web UI in the IBM Cloud console, the service automatically generates a Vault admin token using Vault response wrapping and uses that wrapped token to authenticate the user into the Vault Web UI.

For more information, see Open the Vault Web UI.

Accessing Vault through the CLI, API, or Terraform

Authentication for the Vault CLI, API, or Terraform can be performed using a Vault admin token. Treat the admin token as a highly sensitive credential. Store it securely, use it only for the intended task, and revoke it immediately afterward.

For step-by-step instructions, see Generating an admin token for CLI, API, and Terraform.

Recommended practices

Use the admin token only for Vault initial configuration, administration, and emergency access scenarios. For day-to-day operations, configure Vault authentication methods such as AppRole, Kubernetes, or JWT, or other identity-based authentication mechanisms. This enables applications, workloads, and team members to authenticate directly with Vault using short-lived, least-privilege credentials rather than relying on the admin token.

  • Use the admin token to perform initial setup: enable secrets engines, configure authentication methods, and define access policies.
  • Revoke the admin token after each administrative session.
  • Avoid storing the admin token in scripts or automation. Use a dedicated authentication method instead.
  • A rate limit applies to admin token generation to prevent abuse. If you exceed the limit, wait before requesting a new token.

API operations

The Instance Management API exposes the following operations for managing admin tokens:

  • Generate an admin token – Creates a new Vault admin token for use with the CLI, API, or Terraform. For full request and response details, see Generating an admin token for CLI, API, and Terraform.

  • Revoke all admin tokens – Immediately invalidates all active admin tokens for your instance, requiring new tokens to be generated for future administrative access. See Revoking all admin tokens in the Instance Management API reference.

For authentication requirements, base URL details, and full request and response specifications for both operations, see Instance Management API reference.