3. Authentication and Sessions

3.1 Authentication Modes

PanCTL supports two distinct ways of authenticating:

3.2 Logging In (auth login)

panctl auth login [server] [--server <addr>] [--username <user>] [--password-stdin] [--insecure] [--profile <name>]

Interactive example:

$ panctl auth login
Profile [default]:
Server [realm_dns_name]: 34.63.175.103
Username: finch/alice
Password:
Login succeeded

Usernames are tenant-qualified: <tenant-short-name>/<username> (e.g. finch/alice). A bare name such as admin logs in to the platform tenant. There is no separate --tenant flag on login; the tenant is always part of the username.

Server address resolution (first match wins): a positional argument or --server → the PANCTL_API_SERVER environment variable → the value already stored in the target profile → http://localhost:8000. A bare host/IP is filled in with http:// and port 8000 if you don’t specify them:

panctl auth login 34.63.175.103                     # -> http://34.63.175.103:8000
panctl auth login --server 34.63.175.103:9000        # explicit port is kept
panctl auth login --server https://api.example.com   # explicit https keeps port 443

Supplying a password non-interactively (avoid --password, which does not exist for login; use --password-stdin (below) or PANCTL_PASSWORD, see 5.2):

printf '%s' "$PASSWORD" | panctl auth login 34.63.175.103 --username finch/alice --password-stdin

Other login flags:

3.3 Checking Your Identity (auth whoami)

$ panctl auth whoami
PROFILE:            lab
SERVER:             http://10.97.5.200:8000
USER ID:            u-1
TENANT ID:          t-1
IS PLATFORM ADMIN:  false

Useful for confirming which server and account a profile is pointing at before you run something destructive.

3.4 Logging Out (auth logout)

panctl auth logout                  # clears the active profile's session
panctl auth logout --profile lab    # clears a specific profile

This removes the stored session locally (server, tokens, TLS setting); there is no server-side “logout” call, since the tokens simply expire on their own if left unused.

3.5 API Tokens (auth tokens)

Long-lived tokens you can hand to scripts or CI systems instead of a username/password.

panctl auth tokens create --name ci-runner --expires-in-days 90
panctl auth tokens list --active-only
panctl auth tokens revoke jusKjSv7iJzMmaL9 --reason "rotated"

# Capture just the secret for use in a script:
TOKEN=$(panctl auth tokens create --name ci-runner --expires-in-days 90 --format 'jsonpath={.token}')

Important: the token secret is only ever shown once, at creation time. Store it somewhere safe immediately.

3.6 Using a Pre-Issued Token

export PANCTL_API_TOKEN=vdt1_...
export PANCTL_API_SERVER=10.97.26.200
panctl volumes list

or per-command:

panctl volumes list --token-stdin < token.txt

In this mode, PANCTL_API_SERVER is required (there’s no profile to fall back on), and nothing is written to disk. A rejected token produces a clear error and a distinct exit code (3), which is useful for detecting expired automation credentials in scripts.

3.7 Automatic Session Renewal

You generally never need to think about this: PanCTL renews a profile’s session automatically, either just before it’s known to have expired or transparently after a single authentication failure, and retries the original command once. If renewal itself fails, you’ll see:

error: session expired. Run: panctl auth login --profile <name>