Skip to main content

Roles & Permissions API

Infracast uses five roles. Each maps to a fixed permission set — permissions are not individually assignable, so access is granted by choosing the appropriate role.

RoleLevelIntended for
read-only1Stakeholders who need visibility into assets and findings
auditor2Assessors and auditors — adds audit-log access
security-analyst3Day-to-day operators — can run discovery and audits
tenant-admin4Owns the tenant: users, credentials, integrations
system-admin5Platform operators. Not used in normal customer tenants

Levels matter: they drive the escalation rules described below.

List roles​

GET /api/v1/tenants/{tenantID}/roles

Requires tenant:read. Returns an array (not an object) of every role with its permissions and level:

[
  {
    "role": "read-only",
    "permissions": [
      "tenant:read", "nodes:read", "jobs:read", "findings:read",
      "evidence:read", "poam:read", "questionnaire:read",
      "assessment:read", "rules:read"
    ],
    "level": 1
  },
  {
    "role": "auditor",
    "permissions": [
      "tenant:read", "nodes:read", "jobs:read", "findings:read",
      "logs:read", "evidence:read", "poam:read", "conmon:read",
      "questionnaire:read", "assessment:read",
      "attestation_evidence:read", "rules:read"
    ],
    "level": 2
  }
]

Permission strings are resource:action — for example nodes:read, findings:read, users:manage. The full list per role is returned by this endpoint; treat it as the source of truth rather than hardcoding a copy.

Change a user's role​

PUT /api/v1/tenants/{tenantID}/users/{userID}/role

Requires the roles:manage permission (tenant admin or higher).

Request body:

{ "role": "security-analyst" }

Returns 200 on success. The change is written to the audit log with the previous and new role.

Guard rails​

Four rules are enforced, each returning 403:

RuleMessage
You cannot change your own rolecannot change your own role
You cannot grant a role above your owncannot assign a role higher than your own
You cannot modify a user more privileged than youcannot modify a user with higher role than your own
The target must be in your tenantuser does not belong to this tenant
Tenant admins cannot promote to system-admin

system-admin is level 5 and tenant-admin is level 4, so the "no role above your own" rule blocks it. This is deliberate — system-admin is a platform-operator role that spans tenants, not a stronger customer admin.

An unknown role returns 400 invalid role: must be one of read-only, auditor, security-analyst, tenant-admin, system-admin. An empty role returns 400 role is required.

Locked out of your own tenant?

Because nobody can change their own role, a tenant with exactly one admin cannot self-service a change to that admin. Keep two users at tenant-admin so they can administer each other.