IAM, Policies & Access

Admiral's access model is built on relationships between subjects and scopes. This page explains how access cascades through the resource hierarchy, how policies bundle permissions, and how to grant access at the right level.

The Resource Hierarchy

Access in Admiral flows downward through a nested hierarchy. Granting access at a higher level cascades to everything beneath it.

Organisation
└── (nested / sub-organisations)
    └── Fleet
        ├── Devices
        └── Configuration (attached)

• Organisations are the top-level tenant. They can contain nested sub-organisations (sub-accounts), whose billing rolls up to the root account.
• Fleets live within an organisation and group devices.
• Devices belong to fleets.
• Configurations are attached to fleets and define what runs on devices.

Cascading access

When you grant a role on a scope, it cascades to all resources contained within that scope:

• Granting organisation admin gives full control over all fleets, configurations, rollouts, and devices in that organisation.
• Granting access on a single fleet gives that level of access to the fleet, its devices, and rollouts targeting it.

This means an organisation-wide role is the most powerful grant possible. Use it deliberately.

Fleet access implies config read

Important rule

When a subject is given access of any kind to a fleet, they are automatically granted read access to that fleet's attached configuration.

This ensures that anyone who can see or operate a fleet can understand what is running on it, without needing a separate configuration grant.

Subjects, Relations, and Scopes

A grant is a single statement of the form:

<subject> has <relation> on <scope>

• Subject - a user or a service account.
• Relation - the role being granted (e.g. member, viewer, admin).
• Scope - the resource the relation applies to, identified by a type and an ID (e.g. flotilla:fleet-uuid, organisation:org-uuid).

Available relations depend on the scope type. The platform reports which relations are grantable on each scope type, and whether a relation is "broad" (organisation-wide and cascading).

Granting a Single Fleet

You do not have to grant org-wide access. To give a service account access to just one fleet:

1. Author a policy with a single statement: a fleet-scoped role on the specific fleet.
2. Attach it to the service account.

The service account will then have that role on the fleet, its devices, and read access to the fleet's attached configuration, and nothing else.

Policies

A policy is a reusable, named bundle of grant statements. Instead of wiring up individual grants on every service account, you author a policy once and attach it wherever needed.

Why use policies

• Reusable - attach the same policy to many service accounts.
• Auditable - access is always visible and named, never ad hoc.
• Changeable - editing or detaching a policy updates access cleanly.

Anatomy of a policy

Each policy has a name, an optional description, and one or more statements. Each statement is a (role, scope) pair:

Policy: "dev-team-baseline"
  Statement 1: role=member  scope=organisation:org-uuid
  Statement 2: role=admin   scope=flotilla:fleet-uuid

Onboard in one action

Include an organisation member statement to fully onboard a service account in a single attach. For an API key that can do everything, use an organisation-level admin role, which cascades to all resources.

Broad-access warning

If any statement uses an organisation-wide role, Admiral flags the policy as granting broad access. Any service account the policy is attached to will be able to manage all fleets, configurations, rollouts, and devices in that organisation. Treat these policies with care.

Creating a policy

1. Go to IAM > Policies and click Create Policy.
2. Give it a name and optional description.
3. Add one or more statements. For each:
   • Choose a scope type (e.g. organisation, fleet).
   • Pick the resource that scope applies to.
   • Choose the role.
4. Save.

Only admins, roots, or owners can create or edit policies. Non-admin members can view policies read-only.

Editing and deleting

• Edit a policy to change its statements. Changes propagate to attached service accounts.
• Delete is blocked if the policy is still attached to any service account. Detach it everywhere first.

Attaching Policies

Policies are attached to service accounts. You can attach from either side:

• From a service account (Policies tab > Attach Policy), choose one policy.
• From a policy (Attach to SAs), choose multiple service accounts at once.

Delegation and skipped statements

When you attach a policy, Admiral enforces delegation: you can only grant access you yourself hold. Statements you do not have authority to grant are skipped, not failed. The attach result tells you how many grants were applied and how many were skipped, with a reason for each skip.

This means attaching a broad policy as a limited admin will only apply the parts you are entitled to delegate.

Detaching

Detaching a policy removes the grants it contributed. Access also provided by other attached policies is retained, so removing one policy will not strip permissions another policy still grants.

Who Can Do What

Action	Required role
View service accounts, keys, grants, policies	Member of the organisation
Create / delete service accounts	Admin, root, or owner
Mint / revoke keys	Admin, root, or owner
Create / edit / delete policies	Admin, root, or owner
Attach / detach policies	Admin, root, or owner
Grant / revoke access	Admin, root, or owner (only access you hold)

Service accounts themselves cannot create other service accounts, mint keys, author policies, attach policies, or grant access. There are no machine-to-machine permission chains.

Nested organisations

For a service account in a nested (sub) organisation, both the child-org admin and the root-org admin can manage it. Root admins inherit authority over nested organisations automatically.

Manual Grants

For a single ad-hoc permission, you can add a manual grant directly on a service account's Access tab under Advanced. Choose a scope type, pick the resource, and select a relation.

Prefer policies for anything you will reuse. Manual grants are best reserved for genuine one-offs.

Next Steps

• Service Accounts - create and authenticate machine identities
• Access Explorer - audit effective access
• Webhooks - real-time notifications