BYOC permission tiers — what access to grant, per provider

BYOC Permission Tiers

When you connect your own cloud account (BYOC — Bring Your Own Cloud) to Sencai, you choose exactly how much access to grant. This page gives Sencai employees and customers a single, consistent reference for what to create on each cloud provider, at four levels — from read-only up to autonomous operation.

Use this page before creating credentials in Gravity → Settings → Cloud Credentials — decide the tier first, then follow the provider-specific steps below.

---

The four tiers

Every provider section below maps onto the same four conceptual tiers. Not every provider can express all four natively at the IAM level — where that’s the case, it’s called out explicitly rather than pretending a finer-grained option exists.

Tier	What it allows	Typical use case
1 — Read-only	Inventory scan / import / discovery only. Sencai can see your resources but never changes anything.	First connection, audits, cost visibility, compliance reporting
2 — Operator	Read + non-destructive lifecycle actions (start/stop/reboot/resize). No create, no delete, no IAM/network changes.	Day-2 monitoring and patch management without provisioning risk
3 — Full provisioning	Create, update, delete resources within the granted scope (a specific resource group / project / account, not necessarily the whole cloud account).	Sencai fully manages a defined slice of your infrastructure
4 — Autonomous	Same cloud-side permissions as Tier 3, plus an explicit opt-in on the Sencai side (Gateway PEP autonomy_level: L3) letting an AI agent act without a human approving each action.	Mature deployments, after Tier 3 has been running reliably

Tier 4 is never just a cloud IAM setting — it always requires a corresponding Sencai-side Gateway PEP policy decision (see How this maps to Sencai’s Gateway PEP below). Granting Tier 3-level cloud permissions does not by itself enable autonomous behavior.

Recommended path

Start at Tier 1 for any new account. Move to Tier 2 or 3 once you’re comfortable with what Sencai discovers. Only consider Tier 4 after Tier 3 has been running against real infrastructure without surprises.

---

AWS

AWS IAM policies are fully expressible at the JSON level, so all four tiers map cleanly.

Tier	IAM approach
1 — Read-only	Attach the AWS-managed ReadOnlyAccess policy, or a narrower custom policy scoped to ec2:Describe*, rds:Describe*, s3:GetBucket*/s3:ListBucket, iam:List*/iam:Get*, route53:List*/Get* — whichever services you want inventoried.
2 — Operator	Tier 1 permissions plus ec2:StartInstances, ec2:StopInstances, ec2:RebootInstances. Explicitly deny (or simply omit) ec2:RunInstances, ec2:TerminateInstances, iam:*, ec2:CreateSecurityGroup/DeleteSecurityGroup.
3 — Full provisioning	A custom policy scoped by resource tag or region (Condition: { StringEquals: { "aws:RequestTag/ManagedBy": "sencai" } } is a common pattern) covering ec2:*, rds:*, elasticloadbalancing:* for the services you want Sencai to manage — not the broad AWS-managed AdministratorAccess policy, which grants access far beyond what Sencai needs.
4 — Autonomous	Same as Tier 3, plus enabling autonomy_level: L2/L3 on the corresponding Sencai agent-policy record for this organization (Sencai admin action, not an AWS-side change).

How to connect: create an IAM user (access key) or, preferably, an IAM role Sencai’s platform account can assume cross-account (sts:AssumeRole) — the role option avoids ever handing Sencai a long-lived static secret. Either way, enter the credentials at Gravity → Settings → Cloud Credentials → Add → AWS.

Caution

Today’s default onboarding flow asks for broad AdministratorAccess for simplicity. A published, ready-to-attach least-privilege policy document for each tier is planned but not yet available — until then, use the service list above as your starting point and remove any service you don’t need Sencai to touch.

---

Azure

Azure Role-Based Access Control (RBAC) also expresses all four tiers, via a Service Principal (App Registration).

Tier	Azure RBAC role
1 — Read-only	Built-in Reader role, assigned at the subscription or resource group scope.
2 — Operator	A custom role granting Microsoft.Compute/virtualMachines/start/action, .../restart/action, .../deallocate/action plus Reader’s read actions — no write/delete on any resource type.
3 — Full provisioning	Built-in Contributor role, scoped to the subscription or (preferably) a specific resource group Sencai manages.
4 — Autonomous	Same as Tier 3, plus enabling autonomy_level: L2/L3 on the corresponding Sencai agent-policy record (Sencai admin action, not an Azure-side change).

How to connect:

1. Entra ID → App registrations → New registration.

2. Certificates & secrets → New client secret — copy the value immediately, Azure never shows it again.

3. Subscription (or resource group) → Access control (IAM) → Add role assignment — assign the role from the table above to the app you just registered.

4. Collect four values and enter them at Gravity → Settings → Cloud Credentials → Add → Azure:

   Field	Where to find it
   Subscription ID	Azure Portal → Subscriptions
   Tenant ID	App registration → Overview → Directory (tenant) ID
   Client ID	App registration → Overview → Application (client) ID
   Client Secret	The value from step 2

This is the same flow used for customer onboarding — see lkp-entraid.md (internal, not published here) for a worked example against a real customer tenant.

---

Google Cloud (GCP)

GCP IAM roles map onto the same four tiers via a Service Account.

Tier	GCP IAM role
1 — Read-only	Built-in roles/viewer, or narrower predefined roles like roles/compute.viewer if you only want compute inventoried.
2 — Operator	A custom role with compute.instances.start, compute.instances.stop, compute.instances.reset plus the viewer-equivalent read permissions — no compute.instances.create/delete, no IAM permissions.
3 — Full provisioning	Built-in roles/compute.admin (or roles/editor if Sencai should manage more than just Compute Engine), scoped to a specific project, never organization-wide.
4 — Autonomous	Same as Tier 3, plus enabling autonomy_level: L2/L3 on the corresponding Sencai agent-policy record (Sencai admin action, not a GCP-side change).

How to connect: create a Service Account (IAM & Admin → Service Accounts), grant it one of the roles above, then create and download a JSON key for it. Upload the JSON key at Gravity → Settings → Cloud Credentials → Add → GCP.

---

Hetzner Cloud

Hetzner API tokens have only two native permission levels — there is no IAM system to build a 4-tier ladder from at the provider level:

Hetzner token type	Maps to
Read	Tier 1 (read-only) — this is the entire native ceiling
Read & Write	Tiers 2, 3, and 4 are not distinguishable at the Hetzner API level — a Read & Write token can start/stop, create, and delete equally

Because Hetzner cannot enforce “operator, not full provisioning” itself, Tiers 2/3/4’s actual distinction on Hetzner lives entirely in Sencai’s own Gateway PEP — the agent-policy record’s allowed_action_types/blocked_action_types fields (and autonomy_level) are what actually stop a Read & Write Hetzner token from being used for destructive actions Sencai wasn’t authorized to perform, not anything Hetzner itself checks.

How to connect: Hetzner Cloud Console → Security → API Tokens → Generate API Token → choose Read or Read & Write → enter the token at Gravity → Settings → Cloud Credentials → Add → Hetzner.

Note

Hetzner’s own live-inventory scan (discoverResources()) currently covers server (VM) resources only — floating IPs, volumes, networks, and load balancers are not yet scanned, matching the “start with compute” pattern every other provider’s discovery began with too.

---

Scaleway, OVHcloud, UpCloud

Provisioning adapters exist for these three providers, but live-inventory scan (discovery) is not yet implemented for any of them (still a stub returning no resources, same historical starting point Hetzner had before its own discovery was built). If you need to import existing infrastructure from one of these providers today, the only path is via a Terraform state file import (see Importing Existing Infrastructure), not a live account scan.

Permission-tier guidance for these three will be added once their own discovery implementations land — until then, treat any credential you create for them as Tier 3 (full provisioning) by default, since there’s no scan-only use case to grant Tier 1 for yet.

---

DigitalOcean, Vultr, Linode

Not currently supported. DigitalOcean has a placeholder in Sencai’s provider list but no working adapter behind it yet (“not implemented” if you try to use it). Vultr and Linode aren’t represented in the platform at all yet. Don’t create BYOC credentials for these providers — there is nothing on the Sencai side that would use them today.

---

How this maps to Sencai’s Gateway PEP

Every organization gets a default permissive policy (autonomy_level: L2) when it’s created — cloud-side permissions (the tiers above) and Sencai-side policy are two independent gates, both of which must allow an action for it to actually happen:

• L0 (observe only) — no mutating action is allowed regardless of cloud IAM permissions.
• L1 (suggest only) — only actions initiated by a real, authenticated human are allowed; anything flagged as system/agent-initiated is blocked.
• L2 (execute with approval) — actions matching the policy’s allowed_action_types proceed (this is the default for new organizations).
• L3 (auto-execute) — same action set as L2, but without a human-approval gate in front of it — this is what Tier 4 above actually refers to.

Changing your organization’s autonomy_level is a Sencai admin action (Gravity → Settings → Agent Policies, or ask your Sencai contact) — it is never automatically granted just because you gave broader cloud-side permissions. See Gateway architecture for the full enforcement model if you want the technical detail.