Handle authentication lockouts

Authentication lockout protects the credential-based login endpoints of STACKIT Secrets Manager against repeated failed login attempts. It applies to:

• userpass logins at POST or PUT /v1/auth/userpass/login/{username}.
• AppRole logins at POST or PUT /v1/auth/approle/login.

A lockout affects only new logins and token issuance. Vault tokens that were issued before the lockout remain valid until they expire and can be renewed normally.

A lockout lasts 10 minutes. The rules that trigger a lockout are managed by STACKIT. You cannot view or change them for an individual Secrets Manager instance, user, or AppRole.

How authentication lockout works

Failed logins are evaluated for the protected identity and the request’s source IP:

• Repeated failures for the same identity from one source IP block logins for that identity from that source IP for 10 minutes.
• Failures for the same identity from multiple source IPs block that identity from all source IPs for 10 minutes.

For userpass, the protected identity is the username. For AppRole, it is the Role ID. Clients that share both an identity and a source IP also share the failure state for that combination. Other identities using the same source IP are not affected by a source-specific lockout.

Lockouts expire automatically 10 minutes after they are triggered. Login attempts during an active lockout do not extend its duration. Requests rejected by the instance’s Access Control List (ACL) return 403 Forbidden and do not contribute to authentication lockout.

Understand login responses

Use the HTTP status and error message to determine the next action:

Response	Meaning	Action
400 Bad Request: invalid username or password	The userpass credentials are invalid.	Verify the username and password before retrying.
400 Bad Request: invalid role or secret ID	The Role ID or Secret ID is invalid.	Verify that the application uses the current AppRole credentials.
429 Too Many Requests: user is temporarily locked due to too many failed login attempts	Valid userpass credentials were supplied while a lockout was active.	Stop login attempts and retry after 10 minutes.
429 Too Many Requests: approle is temporarily locked due to too many failed login attempts	Valid AppRole credentials were supplied while a lockout was active.	Stop login attempts and retry after 10 minutes.
403 Forbidden: permission denied	The source IP is not allowed by the instance ACL.	Verify the ACL instead of waiting for a lockout to expire.

To avoid disclosing whether credentials are valid, an invalid credential returns the generic 400 Bad Request response even during an active lockout. A 400 Bad Request response therefore does not confirm whether a lockout is active.

The 429 Too Many Requests response does not include a Retry-After header, the remaining lockout duration, or the lockout scope.

Handle a temporary lockout

1. Stop immediate login retries to prevent a retry loop.
2. For 400 Bad Request, verify the configured username and password or Role ID and Secret ID. Make sure all replicas of your application use the current credentials.
3. For 403 Forbidden, verify that the source IP is included in the instance ACL.
4. For 429 Too Many Requests, wait at least 10 minutes before the next login attempt. Do not continuously submit login requests.
5. Reuse and renew an existing Vault token instead of requesting a new token for every operation.

Changing a password or creating a new Secret ID does not immediately end an active lockout. The new credential can be used after the 10-minute lockout expires.

If a valid login still returns 429 Too Many Requests more than 15 minutes after the last failed login attempt, contact the STACKIT Help Center. Provide the authentication method, instance ID, username or Role ID, request timestamp with time zone, source IP, HTTP status, and error message.

Never include passwords, Secret IDs, access tokens, or Vault tokens in support requests.