Access control — TokenID

TokenID uses a fixed set of roles. Permissions are organized as resource:action pairs, and every sensitive action — anything that writes, deletes, or invokes — emits a row to the audit log automatically.

Roles at a glance

Role	Use it for
owner	Founders, root admins. Only role that can destroy org data or transfer ownership.
admin	Day-to-day platform admins. All ops except destructive org-data actions.
billing	Finance and procurement. Read everything operational, manage payment methods.
developer	Engineers who ship code. Create API keys and provider connections, read everything.
viewer	Read-only dashboards. Stakeholders, contractors, exec read-only access.

Every user has exactly one role. Roles are scoped to the organization; per-workspace roles ride on top of these.

Permission matrix

Cells show actions each role can perform on each resource. Empty means no access.

Resource	owner	admin	billing	developer	viewer
Workspaces	read · write · delete	read · write	read	read	read
Reports	read · write	read · write	read	read	read
Claims	read · write	read · write	—	read	read
Enforcement config	read · write	read · write	—	read	read
Kill switch	read · invoke	read · invoke	—	—	—
Billing	read · write	read	read · write	—	—
API keys	read · write · delete	read · write · delete	—	read · write	—
Provider connections	read · write · delete	read · write · delete	—	read · write	—
Audit log	read	read	read	—	—
Org data (GDPR erasure)	delete	—	—	—	—

owner is the only role that can issue a full org-data deletion — the irreversible erase used for GDPR / right-to-be-forgotten requests. That action writes an audit-log row (org_data.delete) that survives the purge.

Actions explained

Action	Means
`read`	Fetch the resource via `GET`
`write`	Create or update (`POST` / `PATCH`)
`delete`	Destroy the resource (`DELETE`)
`invoke`	Trigger an irreversible operation (kill switch, erasure)

Every write, delete, and invoke writes to the audit log. read does not — it would balloon the log without adding evidence.

Assign a role

From the dashboard: Settings → Team → Invite or click an existing teammate to change their role.

Open the team settings
Go to [token.audit.id/app/settings/team](https://token.audit.id/app/settings/team).
Invite or edit
Click **Invite** for a new teammate, or the row of an existing one to change role.
Pick the smallest role that works
Default to `viewer`. Promote to `developer` for engineers, `admin` for ops, `owner` only for founders.

New invitees default to `viewer`. They cannot mint API keys or change settings until promoted — safe default for a click-through onboarding.

Forbidden responses

When a role lacks the required permission, the API returns 403 Forbidden with a precise reason:

{
  "detail": "role=viewer cannot write api_keys"
}

Use this in your own tooling to surface a clearer message than a generic 403.

Cross-references

Workspaces

Workspace-scoped roles inherit org permissions and add per-workspace ownership.

Audit log

Every sensitive action is logged with the actor, resource, and timestamp.

Data retention

`owner` is the only role that can trigger full org-data erasure.