Authentication and keys

Every call to the API carries a key in the Authorization header:

Authorization: Bearer wt15ak_…

A key is sent only in that header — never in a URL or a query string.

The key

• Format. wt15ak_, then 64 hexadecimal characters and a 6-character checksum. The fixed prefix lets secret scanners recognise a leaked key; a malformed string is refused before any lookup.
• Shown once. The full key appears once, when it is created. WatchTower15 keeps only a one-way hash of it and its last four characters (the console lists a key by name and those four characters, as wt15ak_… and the four).
• One organisation. A key belongs to the organisation you create it in, and acts as you there.

Scopes

A key carries scopes, which are permission names such as servers.view or logs.view. A call needs the scope and your role to hold the same permission, so a key never sees more than the member who owns it: if your role loses a permission, the key loses it with you, on its next call.

You choose the scopes when you create the key and can only choose ones you hold. Grant a key only the areas it needs; one key per job makes a leak small and a revocation clean.

Two scopes change things instead of reading them: incidents.edit acknowledges and resolves incidents, and domains.edit runs domain scans. Ticking either needs the API access edit permission, api_access.edit, besides holding the permission itself, and a key made before they existed has neither. See acting on incidents and scans.

Expiry

Every key expires. You choose how long it lives when you create it, from 1 day to 1 year (365 days). The console’s dialog suggests 90 days, and a key created with no choice also lives 90 days. Seven days before a key expires, WatchTower15 emails its owner. A key is never extended: create a new one and revoke the old.

Emails about your keys

WatchTower15 emails a key’s owner, at the account’s own address:

• When a key is created: New API key “” created, with its name, its last four characters, the organisation, its scopes, when it expires, and the IP address and device it was created from. Never the key itself. If you did not create it, revoke it and reset your password.
• When keys are revoked: one email per revocation, listing the keys it ended (up to 10, then how many more) and why: you revoked it, an administrator or an Admin of the organisation did, your membership ended or was suspended, your password was reset, or WatchTower15 revoked every key as a security measure. A revocation that ends keys in several organisations, such as a password reset, sends one email listing them all.
• Seven days before a key expires, as above.

What revokes a key

A revoked key answers 401 unauthorized from then on. A key is revoked when:

• its owner revokes it, from the API tab of their Profile;
• an Admin revokes it from Organisation → Users, or revokes every key of the organisation with Revoke all keys on Organisation → Settings → Authentication;
• its owner’s membership of the organisation ends or is suspended — restoring the membership does not bring the key back;
• its owner’s password is reset. Changing a password does not revoke keys.

A key also stops answering when its owner’s account is deleted, and when it expires.

Turning keys off for an organisation

Allow members to use API keys, on the API Keys card of Organisation → Settings → Authentication (settings.edit), is on for every organisation unless you turn it off. While it is off, every key of the organisation answers 403 forbidden, no key can be created for it, and the Profile no longer offers it. Turning it off revokes nothing: turning it on again brings every key back. See Organisation settings.

Two-factor authentication and password expiry do not affect keys: a key keeps working while its owner’s organisation requires two-factor authentication they have not set up, or while their password is expired.

Single sign-on organisations

Members who must sign in with single sign-on can create and use API keys only while Allow API keys for SSO-managed members is on (off by default), on the same API Keys card. Switching it off revokes nothing: their keys simply stop answering until it is switched on again. See single sign-on.

What WatchTower15 records

Each revocation is emailed to the key’s owner (above).

For each key: its name, the areas it may read, the organisation it belongs to and the member it acts for, when it was created and when it expires, when it was last used and the IP address of that use, and, if it was revoked, when, why and by whom. It never keeps the key itself. For each key and day it also counts the calls made to each operation, how many failed or were refused for exceeding a limit, how much data they returned and when the last call was made. Key creation, revocation and expiry appear in the audit trail; the counts appear on Organisation → Audit → API usage. Key records are kept with your account data, revoked and expired keys included; the daily counts are deleted after 400 days.