Settings and API tokens¶

Settings holds your own sign-in security and, for owners, install-wide settings. Open Settings in the sidebar. The header shows the email you are signed in with.

Section	Who sees it
Authenticator	Everyone
Password	Everyone
Timezone	Owners
Hostname	Owners
Config export	Owners
Support access	Owners
Manage users link	Owners and admins. See Users and roles.

Authenticator¶

If you already have one, the section says "An authenticator app is confirmed for this account."

If you have none, or an owner reset your MFA:

Select Set up authenticator.
Scan the QR code, or type the key under Manual entry into your app.
Enter the 6-digit code.
Select Confirm.

The app lists the entry as Watchtower with your email. Until you confirm one, you sign in with an emailed code.

Password¶

Enter your Current password and a New password.
Select Change password.

The page shows "Password updated." The new password needs at least 12 characters and must not be a common password. Other sessions stay signed in.

To sign out everywhere, reset your password instead. On the sign-in page, select Forgot password, enter your Email, and select Send reset link. The page says "If that email belongs to an active account, a reset link is on its way." The link is valid for 1 hour. On Choose a new password, enter a password and select Update password.

Timezone¶

Licence reminders are sent at 09:00 in this timezone. The default is UTC.

Enter an IANA timezone name, such as Europe/Berlin or Asia/Kolkata.
Select Save timezone.

An unknown name shows unknown timezone.

Hostname¶

Add a new web address for the portal, Edges, and Apps. The section shows the current name.

Before you start, make sure the new name already points to your install in DNS.

Enter the name in Hostname, for example watchtower.acme.com.
Choose a DNS mode: Domain hosted elsewhere, or Existing Route 53 zone. For the second, enter the Zone id.
Select Add hostname.

Edges and Apps switch to the new name on their own. The old name keeps working for 90 days, and the section says " is removed on ." Owners and admins get reminders 30 and 7 days before.

Errors: hostname, hostname mode, hostname did not resolve, hostname is already in use, and a message that a change is already in progress. Only one change can run at a time.

Config export¶

The section says: "Sites, groups, role bindings, templates, layers, alarm rules, and settings. Passwords are not included. Secrets stay encrypted for this install's data key."

Select Download bundle. The browser saves bundle.tar.zst. Store it securely. If the download fails, the page shows "Export failed".

Support access¶

Lets Privitty support view your install's resources, read-only, for a limited time.

"Support access is off." means this install has no support access.
Otherwise enter a number of days from 1 to 30 (default 7) and select Grant support access for N days. The section shows "Support can assume the role until ."
Select Revoke to end access early. The section then says "The support role exists and cannot be assumed."

Grants and revokes are recorded in Audit.

API tokens¶

Use an API token to call the Watchtower API from scripts. The portal has no screen to create, list, or revoke tokens.

How tokens work¶

A token acts as the owner who created it.
A token has scopes. Each is a permission name from Roles and permissions.
A request works only if the scope is on the token and the owner's role still allows it.
A token lasts 1 hour to 90 days. It stops working when it expires or when its owner is disabled.
Watchtower shows the token once. Save it right away.

Create a token¶

You must be an owner with a role over the whole organization, and signed in to the portal. A token cannot create another token. The request uses your browser session, so copy two cookie values from your browser's developer tools: wt_session and wt_csrf.

Warning

wt_session signs in as you. Keep it out of shared files and terminals, and sign out when you finish.

SESSION='<wt_session value>'
CSRF='<wt_csrf value>'

curl -s -X POST https://watchtower.example.com/api/v1/auth/api-tokens \
  -H "content-type: application/json" \
  -H "x-csrf-token: $CSRF" \
  -b "wt_session=$SESSION; wt_csrf=$CSRF" \
  -d '{"name": "ci-inventory", "scopes": ["device.view", "telemetry.view"], "ttl_hours": 720}'

Field	Rules
`name`	1 to 64 characters.
`scopes`	1 to 16 different permission names.
`ttl_hours`	1 to 2160. Default 24.

The response includes the token, which starts with wt_:

{
  "id": "0192f0c1-0000-7000-8000-000000000000",
  "token": "wt_...",
  "name": "ci-inventory",
  "scopes": ["device.view", "telemetry.view"],
  "expires_at": "2026-11-25T13:00:00+00:00"
}

Error	Cause
`unauthorized`	No valid session, or the second factor was not completed.
`forbidden`	You are not an organization owner, or you used a token.
`csrf`	The `x-csrf-token` header is missing or wrong.
`unknown scope`, `duplicate scope`	A scope is not a permission name, or appears twice.

Use a token¶

Send it in the Authorization header. You need no cookies.

export WT_TOKEN='wt_...'

curl -s -H "Authorization: Bearer $WT_TOKEN" \
  https://watchtower.example.com/api/v1/devices

A missing scope or a role that no longer allows the action returns forbidden. An expired token, or one whose owner is disabled, returns unauthorized.

Job	Scopes
Read-only inventory	`device.view`, `telemetry.view`
Enrol Edges from a pipeline	`device.enroll`, `device.view`
Export the audit log	`audit.view`

What the portal cannot do¶

It cannot list your tokens.
It cannot revoke a token. Use short lifetimes. To stop every token of one owner, disable that user. That cannot be undone in the portal.
It cannot show a token again after creation. Create a new one.

Each new token is recorded in Audit as auth.api_token.create. Filter by that action to see who created tokens and when.

Not in Settings¶

The email sender and mail server are set when Watchtower is installed. To see mail status, open Health.