Organizations, projects and roles

Organizations

An organization is your tenant. Members, API keys, cloud connections, CI bindings, fleets, collectors, reports, findings and evidence all belong to exactly one organization, and every request is checked against the caller's current membership. A role is never taken from the request or from a cached session.

Roles

Role	Can
viewer	Read.
analyst	Read and write: import reports, manage issues, request evidence packs, gate key releases.
auditor	Read, and read the audit log.
administrator	Everything above, plus members, API keys, cloud connections, CI bindings, fleets and organization settings.

Every change is recorded in the organization's audit log.

Permissions

Each role is a set of four permissions. The role is read again on every request, and a membership that is pending, quarantined or revoked gets none of them.

Permission	viewer	analyst	auditor	administrator	Needed for (examples)
read	yes	yes	yes	yes	Every list and detail view: reports, findings, issues, detections, attack paths, compliance, policies, webhook status.
write		yes		yes	Import a report; create, assign and update issues and notes; exceptions and snoozes; resolve a detection; scan targets; registry upload; re-attest a host; Post to Slack.
audit			yes	yes	Read the audit log and issue history.
connections				yes	Members, invitations, projects and project grants, organization API keys, alert destinations, cloud connections, fleets, CI bindings, registry credentials and trust policy, rule levels and profiles, the release-gate policy, suppression rules, detection mutes, retiring and restoring reports, key-release holds, TCB rollouts, the Confidential Space token audience.

In the console, actions marked for writers need analyst or administrator; actions marked for administrators need administrator. The console tour lists the role each action needs, page by page.

Some actions need a signed-in person and refuse every API key, whatever its role: managing members and invitations, managing organization API keys, configuring alert destinations, and approving a measurement pin request.

Invite someone

Administrators manage members under Settings › Members.

1. Choose Invite someone, enter the person's email or identity-provider subject, and choose a role.
2. untrust shows an invitation link once. Send it yourself; untrust does not send email. Only a digest of the link is stored, so a lost link cannot be recovered: revoke it and create a new one.
3. The invitee opens the link and signs in through your identity provider as the invited person.

An invitation is single-use, expires after 7 days, and can be revoked. The link on its own grants nothing: sign-in succeeds only when the identity provider's subject matches the invited subject exactly, or when the provider asserts a verified email equal to the invited email. If your identity provider does not verify email ownership on every connection, invite by subject instead.

The token travels in the link's URL fragment, which browsers do not send to servers, so it does not appear in access logs or referrer headers.

Change a role or remove a member

• Change role takes effect on the member's existing sessions immediately.
• Remove ends access at once, including open sessions. History and audit references are kept.
• The last administrator cannot be demoted or removed. Promote another administrator first.

Only a signed-in administrator can invite, change roles or remove members. An API key cannot, whatever its role, so a leaked key can never grant access.

Projects

Projects group resources inside an organization: organization, then project, then an optional environment label. Each cloud connection, fleet, CI binding and registry credential belongs to at most one project. Resources in no project are Unassigned.

Limit	Value
Projects per organization	200
Project name	1 to 120 characters, unique ignoring case
Description	Up to 2000 characters
Environment label	1 to 32 characters of a-z, 0-9 and -, for example prod or staging

Only organization administrators create, rename, archive and assign projects, and move resources between them. Archiving a project keeps its assignments but refuses new ones, and grants and project API keys on it stop working. There is no way to unarchive a project.

Restrict members to projects

Restricting members to projects is an opt-in setting for the whole organization. It is off by default. Until it is on, projects only filter what you see, and every member has organization-wide access.

An administrator turns it on under Settings › Projects (Turn on). Turning it off again is always allowed: every member goes back to organization-wide access and no data is lost.

With the setting on, a member has one of two access modes:

• Organization: the organization role applies to every project and to Unassigned.
• Projects: the member sees only the projects they hold a grant on. A project grant is viewer (read), analyst (read and write) or admin (read, write and manage the project). Unassigned is hidden unless they are granted it, as viewer or triage.

Only organization viewer and analyst members can be restricted to projects. Administrators and auditors always have organization-wide access. Changing a member's organization role clears their project grants and revokes the project API keys they created.

Reports, findings, issues and detections follow the project of the resource they came from. An out-of-scope resource reads as missing, not as forbidden. Compliance, policies, evidence packs and the audit log are organization-wide, and project-restricted members cannot use a few organization-wide controls: Post to Slack, organization-wide alert destinations and the Relay panel.

What a project admin can do

• Create project API keys under Settings › Projects › Project keys: role viewer or analyst, expiry 1 to 365 days, from a signed-in session only. A project key never sees Unassigned and never exceeds its creator's current grant.
• Claim an Unassigned resource into a project they administer. This needs admin on the project and triage on Unassigned. Claims are audited as project.claimed.
• Add up to 10 alert destinations scoped to the project; see Alerts and webhooks.
• Write to reports, issues, detections and exceptions in the project.

Every project write also needs the organization write permission, so an organization viewer with a project admin grant still cannot write. In practice, project admins are organization analysts.

API keys

An API key is a bearer credential for scripts, CI jobs and SIEM pulls. Each key belongs to one organization and carries one role.

• Create: Settings › General › API keys › New key, as a signed-in administrator. Pick the narrowest role that works: viewer for reads, analyst to write (for example untrust release verify or untrust report-upload), auditor to read the audit log.
• Store: the key is shown once. untrust keeps only its SHA-256 digest. Keep the key in your CI secret store, never in a repository. Every key starts with untrust_ and carries a checksum, so secret scanners can recognise a leaked key.
• Expiry: 30, 90 or 365 days. Settings shows when each key was last used.
• Limit: at most 50 active keys per organization, project keys included.
• Capped by its creator: a key never does more than the administrator who created it can do now. If they are demoted, the key is capped at their new role; if they are removed, the key stops working. Before an administrator leaves, create replacement keys under someone who stays.
• Revoke: takes effect on the next request.

Use a key as a bearer token, or with the CLI through UNTRUST_API_KEY:

export UNTRUST_API_KEY=...   # from your secret store
untrust api get https://app.untrustsecurity.com/v1/organizations/<org>/issues

A revoked or expired key gets HTTP 401; a key whose role is too narrow gets HTTP 403. The CLI exits non-zero and says which.

API keys are not used for CI evidence upload, which uses the pipeline's own short-lived identity token (Send evidence from CI), or for collectors, which sign with their enrolled key.

Sign-in and sessions

Your untrust contact sets up sign-in through your identity provider for your deployment; it is not configured self-service in the console. Sign-in uses OpenID Connect with PKCE and asks only for openid and email.

• Roles and memberships always come from untrust, never from identity-provider claims.
• A console session lasts the shorter of your identity provider's token lifetime and 1 hour, and is not refreshed. Sign in again when it ends.
• Sign out ends your untrust session only, not your identity provider session.
• untrust does not check for multi-factor authentication. Enforce MFA in your identity provider.

Audit log

The audit log records every change in your organization: who did what, to which resource, and when.

• Where: Settings › General › Audit log. Filter by group (the part of the action name before the dot) and use Load more to page back.
• Who: administrators and auditors.

Field	Meaning
sequence	Position in your organization's log, increasing.
actor	Who acted: a member identity, apikey:<id>, collector:<id> or service:<name>.
action	What happened, for example apikey.created.
resource	What it happened to, by id.
observed	When.

Entries record ids, never an invitee's email or an invitation link.

Read the log from the API with an auditor or administrator key, 50 entries per page:

untrust api get "https://app.untrustsecurity.com/v1/organizations/<org>/audit?order=desc"
untrust api get "https://app.untrustsecurity.com/v1/organizations/<org>/audit?before=<sequence>&order=desc"

Use after=<sequence> to read forward from a known entry. The console has no audit-log export; to keep a copy, page through the API.

Action names

Area	Actions
Sign-in and members	session.*, invitation.*, membership.*
API keys	apikey.created, apikey.revoked
Projects	project.*
Alerts	webhook.*, alert_destination.*, alert.posted
Reports and exports	report.imported, report.retired, report.restored, export.created
Triage	issue.*, exception.*, finding.snoozed, finding.unsnoozed
Rules and policy	rule.*, policy.gate_changed, suppression_rule.*, detection_mute.*, custom_rule.*, custom_buildiac_rule.*
Connections	connection.*, ci.*, registry.*
Fleets and hardware	fleet.*, collector.enrolled, collector.revoked, hardware.*
Key release	key_release.held, key_release.hold_lifted, cs_token.audience_set