CLI & API

Last updated on May 11, 2026

Prerequisites

Create a service account for your STACKIT project and note its email address.
Add the service account to the project.member group in the permissions section.
Create an access token for the service account.

With this access token you can either continue using the STACKIT CLI or the API directly to provision your instances and users.

Secrets Manager API

If you prefer to interact with the API directly, visit the OpenAPI specification.

Interacting with your Secrets Manager instance

Vault CLI

Install the CLI as described in the Vault Documentation. Set the cluster address as environment variable and login with the userpass method to manage your credentials via CLI:

export VAULT_ADDR=https://prod.sm.eu01.stackit.cloud

Authentication

To authenticate yourself against the Vault CLI, use the userpass method. For this, you have to create a new user in your Secrets Manager Instance and afterwards, use the username and password to authenticate yourself:

vault login -method=userpass username=<username> password="<password>"

With this authentication method, a token is deposited in your system which is used for future authentication. This token has a default TTL (time-to-live) of 15 min.
You can also maintain this token, e.g. increase the TTL, view it, delete it etc.

For more information visit the HashiCorp token documentation.

Secrets Path @STACKIT

As the name suggests, this is the path that describes the desired secret path.

HashiCorp Secrets Path: [Secrets-Engine]/data/[Secrets-Name]
STACKIT Secrets Path: [Secrets-Manager-ID]/data/[Secrets-Name]

The screenshot shows the secrets manager details and highlights the secrets manager id.

The screenshot shows the secrets manager secret's name.

You can also maintain your secrets in a folder structure. This could look like this: SecretsFolder/SecretsName

Basic Examples

Write a secret:

vault kv put -mount=<secrets-manager-id> app1/mysecret foo=bar

Output:

===================== Secret Path =====================
<secrets-manager-id>/data/app1/mysecret

======= Metadata =======
Key                Value
---                -----
created_time       2024-11-15T01:52:23.434633061Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            5

Read a secret:

vault kv get -mount=<secrets-manager-id> app1/mysecret

Output:

======= Secret Path =======
<secrets-manager-id>/data/app1/mysecret

======= Metadata =======
Key                Value
---                -----
created_time       2024-11-13T21:58:32.128442898Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            3

======= Data =======
Key                Value
---                -----
foo                bar

Renew your token to keep it valid for 30 min:

vault token renew --increment=30m

For further information, please see the HashiCorp documentation.

Vault API

You can use any client which is compatible to HashiCorp Vault KV Version 2 by using the authentication “UserPass” with the BaseURL: https://prod.sm.eu01.stackit.cloud

Authentication

To authenticate, you will need a username and a password, which you can create in your Secrets Manager instance (see above). With that you can use the userpass endpoint to generate a token that you can use for further API requests.

curl --request POST \
  --data '{ "password": "" }' \
  /v1/auth/userpass/login/<username>

This token is valid for 15 min and can be maintained via API or CLI.

You can find further information in the HashiCorp documentation

Basic examples

{ "data": { "key": "", "value": "" }, "options": { "max_versions": 5 } }

curl --header "X-Vault-Token: <token>" \
  --request POST \
  --data @payload.json \
  /v1/<secrets-manager-id>/data/<secret-name>

curl --header "X-Vault-Token: <token>" \
  --request GET \
  /v1/<secrets-manager-id>/data/<secret-name>

Further information can be found in the HashiCorp documentation.