Administration guide

For org admins: who can do what, how people and machines get in, and the controls that apply to the whole org. Every change below is audited (GET /v1/orgs/{org}/audit-events). An inaccessible org or project always answers 404, never 403, so its existence is not revealed.

Roles

A custom role (/v1/orgs/{org}/roles) lists exactly the permissions it grants, by permission name such as read_telemetry, and replaces a built-in role for the member who holds it. Access policies (/v1/projects/{prj}/access-policies) restrict what a role can query by predicate. effect must be restrict; the field is service.name, deployment.environment.name or attr:<key>, and values is an array, for example {"effect":"restrict","field":"service.name","op":"eq","values":["checkout"]}.

Members, defaults and access requests

• Add a member with POST /v1/orgs/{org}/members. If you leave out role, the org's default role applies.

• Set the default in PATCH /v1/orgs/{org}/settings as default_role (project_admin, engineer or read_only; never org_admin). It also applies to users created by SCIM when no group mapping or SSO role says otherwise. SSO's jit_role wins for SSO sign-ins.

• Access requests let a member ask for more instead of asking an admin out of band. POST /v1/orgs/{org}/access-requests with project_id, role, reason and duration_hours (1 to 720). Org admins are emailed. An admin approves (.../approve) or denies (.../deny) with an optional note; nobody can approve their own request. Approval grants the project role until the duration ends, when the previous role is restored automatically. Requester, approver, decision and expiry are all in the audit log. Members see their own requests, admins see all.

Single sign-on, SCIM and MFA

Configure the org's SSO policy at /v1/orgs/{org}/sso (see Single sign-on): verified domains, enforce SSO, JIT role, break-glass members, MFA and the session cap. SCIM provisioning and group-to-role mapping are described in SCIM.

Org settings

GET|PATCH /v1/orgs/{org}/settings: IP allowlist (CIDRs; the allowlist scopes are org, api_keys, ingest and sessions), allowed email domains, custom SMTP (the password is write-only), default retention, session length and the default role. caller_ip_allowed tells a locked-out admin why a write was refused.

Machine access

• Service accounts (/v1/orgs/{org}/service-accounts) hold scoped, expiring wta_ keys; limit them with allowed CIDRs. Create a key with name, expires_in_days and scopes (all three are required; a request that misses some answers one 422 listing every missing field, for example {"name":"storefront-ci","expires_in_days":365,"scopes":["ci:write"]}). Which scopes each kind of key takes, and what ci:write allows, is in Keys and scopes. There is no "disable" action: DELETE the account to revoke all its keys, or DELETE one key.

• Personal access tokens (/v1/me/tokens) always carry an expiry.

• Workload identity federation removes stored keys for cloud workloads. Trust an external identity for a service account with POST /v1/orgs/{org}/service-accounts/{id}/workload-trusts:

  Field	Meaning
  provider	aws, gcp, azure or oidc (Kubernetes and any OIDC issuer). GCP and Azure (with tenant) fill in the issuer; AWS and oidc need issuer and jwks_uri (https).
  audience	The aud the workload's token must carry.
  subject	The exact sub, or a prefix ending in * (never * alone).
  claims	Extra claims that must match, for example {"tid": "..."}.
  scopes, ttl_s	What the minted key may do (never ingest:*) and how long it lives (60 to 3600 s).

  The workload then posts its own token to POST /v1/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, subject_token=<its identity token> and client_id=<trust id>, and receives a short-lived wta_ access token. Every failure answers invalid_grant, so a caller learns nothing about the trust. No secret is stored or sent by the workload.

Teams are referenced by id everywhere in the API: GET /v1/orgs/{org}/teams returns each team's id and name, PUT /v1/orgs/{org}/teams/{id}/members takes {"user_ids": [...]} (the complete list, at most 1000, all members of the org) and PUT /v1/projects/{prj}/team-grants/{team} takes the team id in the path. Only the as-code TeamMembers kind accepts a team name (team: <Team name>, resolved to the id on apply).

Identity provider connections

POST /v1/orgs/{org}/idp-connections/{id}/test (needs ManageSecurity) checks a connection and answers {"ok": true|false, "message": "..."}. LDAP binds with the service account and runs the user search; SAML loads the IdP certificates and the SP key; a disabled connection answers ok: false. Any other kind (JWT, proxy, OIDC) only has its stored settings validated: the test makes no request to the OIDC issuer, so a sign-in is the real proof. The org's own sign-in policy is Single sign-on.

Org groups

An org that manages several orgs can group them (/v1/orgs/{org}/groups). A group holds a policy (the same fields as org settings except SMTP) and role templates. POST .../push applies the policy and creates each template as the custom role group/<name> in every member org. You must be an org admin of an org to add it to a group, and again at every push: orgs where you no longer are one are skipped and reported. Each org belongs to at most one group. Pushes are audited in the member org's own log.

For a user who belongs to several orgs, GET /v1/me/org-overview shows project, key and member counts and daily event volume per org, and GET /v1/me/dashboards lists the dashboards of every project they can read. Both are read-only and only show orgs and projects the user is a member of.

Security administration

Detection rules map to MITRE ATT&CK (mitre: [{tactic, technique}]); filter signals with ?technique= or ?tactic=. Content packs install with POST /v1/projects/{prj}/security/rule-packs/install. Keep rules as code (kind: SecurityRule, the watchtower_security_rule Terraform resource) and check a rule against sample logs before applying it with wtctl security test rule.yaml sample.ndjson.

Cost sources

Besides export buckets, cost sources can poll the cloud billing APIs without a bucket: kinds aws_ce (Cost Explorer), azure_cost (Cost Management) and gcp_billing (the BigQuery billing export). Create one with credentials_ref pointing at a secret that holds the credentials; see Cloud cost.

Disaster recovery

What you configure (retention, archive, export) versus what the operator runs: recommended DR settings.