Credential rotation

Two flows: changing the current user's password (in-session) and rotating to a new identity (re-construct the client).

In-session password change

client.auth.change_password(old_password="hunter2", new_password="newpass!")

The SDK:

1. Calls PUT /users/me/password with the old and new values.
2. On a 2xx, updates the in-memory password store and invalidates the cached token.
3. Subsequent calls trigger a lazy re-login with the new password.

The application continues uninterrupted. No re-construction of RtlsClient is needed.

Wrong-old-password handling

A wrong old password raises ValidationError (or AuthenticationError depending on server response). Catch it at the call site:

from rtls_sdk import ValidationError

try:
    client.auth.change_password(old_password="wrong", new_password="…")
except ValidationError:
    log.warning("rejected: old password incorrect")

Rotating to a new identity

To switch which user the client speaks as, construct a new client:

old = RtlsClient.from_env()
old.close()

new = RtlsClient(username="new@example.com", password="…", base_url="…")

There's no client.login_as(...) shortcut — identities are bound at construction so the audit trail (X-User-Email) is unambiguous.

Rotating tokens (BYO mode)

In BYO-token mode (see BYO token), the SDK can't refresh tokens on its own. When you receive a fresh token from your token issuer, construct a new client:

client.close()
client = RtlsClient(token=new_token, base_url=...)