Skip to content

Bring-your-own token

If you already have a server-issued token (a long-lived service account, an external SSO flow, a refresh token rotated by your infrastructure), pass it directly:

from rtls_sdk import RtlsClient

client = RtlsClient(token="opaque-server-token", base_url="https://rtls.example.com")
nodes = client.nodes.list()

Caveats

  • No re-login on expiry. The SDK doesn't know your password and cannot refresh the token. A 401 raises AuthenticationError immediately — there is no automatic re-login.
  • You catch and recover. Wrap calls in a handler that catches AuthenticationError, fetches a fresh token from your issuer, and re-constructs the client.
from rtls_sdk import AuthenticationError, RtlsClient

def with_fresh_token():
    return RtlsClient(token=mint_token(), base_url=...)

client = with_fresh_token()
try:
    tags = client.tags.list()
except AuthenticationError:
    client.close()
    client = with_fresh_token()
    tags = client.tags.list()

The default from_env() path (username + password) avoids this entirely: on 401, the SDK silently re-authenticates and replays the request.

When to choose BYO mode

  • You can't store the password in the application's environment.
  • Tokens come from an external mint (SSO, federated identity).
  • You want explicit control over token rotation cadence.

Otherwise, prefer username + password — the SDK handles the lifecycle for you.

Loading secrets from a manager

If your secret-management policy forbids passwords in environment variables, load them from your secret manager and pass them in explicitly:

import boto3, json
secret = json.loads(
    boto3.client("secretsmanager")
    .get_secret_value(SecretId="rtls/qa")["SecretString"]
)
client = RtlsClient(
    username=secret["email"],
    password=secret["password"],
    base_url=secret["base_url"],
)

See security for the threat model and the secret managers the SDK has been tested against.