Configure and use AppRoles

AppRole is an authentication method for applications and automated workloads. Instead of a username and password, an application authenticates with a Role ID and a Secret ID and receives a Vault-compatible token.

AppRole authentication is currently available as a private preview.

How AppRole authentication works

An AppRole consists of:

• A Role ID that identifies the AppRole.
• One or more Secret IDs that authenticate a workload for that AppRole.
• A permission setting that grants read-only or read and write access to the Secrets Manager instance.
• Default lifetime and usage limits for newly created Secret IDs.

The Role ID remains stable until you delete the AppRole. Secret IDs can be created and deleted independently, which allows credential rotation without changing the Role ID.

A Secret ID is returned only when it is created. Store it securely before continuing. You cannot retrieve it again.

Secret ID settings

You define the following defaults when creating an AppRole:

Setting	Default	Description
write	false	Set to true to grant read and write access. The default grants read-only access.
secret_id_num_uses	0	Maximum number of successful logins with each newly created Secret ID. 0 means unlimited use.
secret_id_ttl	0s	Lifetime of each newly created Secret ID. 0s means that the Secret ID does not expire based on time.

Enter the duration as a whole number followed by s for seconds, m for minutes, or h for hours, for example 30s, 15m, or 24h. To specify one day, use 24h; 1d is not supported.

The settings are copied to a Secret ID when it is created. Updating the AppRole changes the defaults for future Secret IDs but does not change existing Secret IDs.

Prerequisites

• You have access to the AppRole private preview.
• You have created a Secrets Manager instance.
• You have an access token with permission to update the instance.
• You know the project ID and Secrets Manager instance ID.
• The source IP of the workload is allowed by the instance’s Access Control List (ACL).

Set the values used in the following examples:

export AUTH_TOKEN=<your-access-token>
export PROJECT_ID=<your-project-id>
export INSTANCE_ID=<your-instance-id>
export SM_API_URL=https://secrets-manager.api.eu01.stackit.cloud
export SM_INSTANCE_URL=https://prod.sm.eu01.stackit.cloud

Create an AppRole

Create a read-only AppRole for an automated workload:

curl --request POST \
  --header "Authorization: Bearer $AUTH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "description": "Read-only deployment workload",
    "write": false,
    "secret_id_num_uses": 0,
    "secret_id_ttl": "24h"
  }' \
  "$SM_API_URL/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/approles"

The response contains the generated Role ID:

{
  "role_id": "3f7ab266-3a25-43e0-8db1-3f9af8c80782",
  "write": false,
  "secret_id_num_uses": 0,
  "secret_id_ttl": "24h0m0s",
  "description": "Read-only deployment workload"
}

Store the returned role_id for the following requests:

export ROLE_ID=<your-role-id>

Create a Secret ID

Generate a Secret ID for the AppRole:

curl --request POST \
  --header "Authorization: Bearer $AUTH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"description":"Production deployment credential"}' \
  "$SM_API_URL/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/approles/$ROLE_ID/secretids"

The response contains the Secret ID and its version:

{
  "version": 1,
  "secret_id": "07c053e5-c548-4873-bb93-9a741cd96aa3",
  "num_uses": 0,
  "ttl": "24h0m0s",
  "description": "Production deployment credential"
}

Save secret_id immediately in the credential store used by your workload. Keep the version value so that you can list, update, or delete this Secret ID later.

Log in with an AppRole

Send the Role ID and Secret ID to the Vault-compatible AppRole login endpoint:

curl --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "role_id": "<your-role-id>",
    "secret_id": "<your-secret-id>"
  }' \
  "$SM_INSTANCE_URL/v1/auth/approle/login"

The token is returned in auth.client_token:

{
  "auth": {
    "client_token": "<vault-token>",
    "lease_duration": 900,
    "renewable": true
  }
}

Repeated login attempts with an incorrect Secret ID can temporarily lock AppRole authentication for the Role ID. Creating or rotating a Secret ID does not immediately clear an active lockout. For response handling and retry guidance, see Handle authentication lockouts.

Use the token as an X-Vault-Token header when accessing secrets:

curl --header "X-Vault-Token: <vault-token>" \
  "$SM_INSTANCE_URL/v1/$INSTANCE_ID/data/<secret-name>"

For token renewal and revocation recommendations, see Session and token handling.

Rotate a Secret ID

To rotate a Secret ID without interrupting access:

1. Create another Secret ID for the same AppRole.
2. Store the new Secret ID in the workload’s credential store.
3. Update the workload to use the new Secret ID.
4. Verify that the workload can authenticate.
5. Delete the previous Secret ID by its version.

Delete the previous Secret ID:

export SECRET_ID_VERSION=<previous-secret-id-version>

curl --request DELETE \
  --header "Authorization: Bearer $AUTH_TOKEN" \
  "$SM_API_URL/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/approles/$ROLE_ID/secretids/$SECRET_ID_VERSION"

Deleting an AppRole invalidates all Secret IDs associated with it.

Management endpoints

Operation	Method and path
List AppRoles	GET /v1/projects/{projectId}/instances/{instanceId}/approles
Create an AppRole	POST /v1/projects/{projectId}/instances/{instanceId}/approles
Get an AppRole	GET /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}
Update an AppRole	PUT /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}
Delete an AppRole	DELETE /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}
List Secret IDs	GET /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids
Create a Secret ID	POST /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids
Get Secret ID metadata	GET /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids/{secretIdVersion}
Update a Secret ID description	PUT /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids/{secretIdVersion}
Delete a Secret ID	DELETE /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids/{secretIdVersion}

Listing or retrieving Secret ID metadata does not return the Secret ID itself. For the complete request and response schemas, see the Secrets Manager API specification.

Security recommendations

• Use a separate AppRole for each workload or trust boundary.
• Grant read-only access unless the workload must create or change secrets.
• Set a finite Secret ID lifetime and usage limit where the workload permits it.
• Store Secret IDs in a dedicated credential store and never commit them to source control.
• Do not write Role IDs, Secret IDs, or Vault tokens to application logs.
• Use multiple Secret IDs to rotate credentials without changing the Role ID.
• Delete unused Secret IDs immediately.
• Renew an existing Vault token instead of logging in again for every API request.