Writing policies

A policy is a JSON document of statements. Each statement says whether an effect applies to a set of actions on a set of resources, optionally gated by conditions.

{
  "version": "2024-01-01",
  "statements": [
    {
      "sid": "ReadInstances",
      "effect": "allow",
      "actions": ["compute:ListInstances", "compute:GetInstance"],
      "resources": ["crn:compute:*:my-account:instance/*"]
    }
  ]
}

version is always 2024-01-01. Anything else is rejected.

Choose the policy scope

Account policies belong to one account and attach to its roles and service accounts. They grant account service actions. Organization policies belong to Workspace and grant workspace:*, billing:*, quota:*, and audit:*. Attach them to users or groups, or explicitly delegate them to an account role or service account. The document format is shared, but the permission domains are separate. actions: ["*"] and action exclusions apply only within the policy’s domain. An account administrator policy cannot grant organization access. An organization policy cannot grant ordinary account resource access. The console’s visual editor offers services appropriate to the selected scope. JSON editing uses the same rules; writing an action from the other scope does not make it effective.

Statements

string, optional

A label for your own use. It has no effect on evaluation.

allow | deny

required

Lowercase. An explicit deny beats every allow in the policy domain being evaluated.

array

required

Exactly one of the pair. Setting both, or neither, is rejected when the document is saved.

array

required

Exactly one of the pair, same rule.

array, optional

All of them must hold for the statement to apply.

Actions

Actions are service:Action, and * is the only wildcard.

"actions": ["compute:GetInstance"]        // one action
"actions": ["compute:*"]                  // every compute action
"actions": ["compute:List*", "compute:Get*"]  // reads, by convention
"actions": ["*"]                          // everything

Resources

Resources are CRNs, with * as the only wildcard. The colon and slash layout is compared literally, so the shape has to be right:

"resources": ["crn:compute:sa-saopaulo-1:my-account:instance/*"]
"resources": ["crn:compute:*:my-account:instance/*"]        // any region
"resources": ["crn:dns::my-account:zone/example.com"]       // global: empty region
"resources": ["crn:workspace:::user/*"]                           // org-scoped: both empty
"resources": ["*"]                                          // anything

Some resources are named rather than UUID-keyed, which makes a naming convention directly policy-able: crn:certificate::my-account:certificate/prod-*.

Naming by exclusion

not_actions and not_resources cover everything except what they list.

{
  "sid": "NothingOutsideMyAccount",
  "effect": "deny",
  "actions": ["*"],
  "not_resources": ["crn:compute:*:my-account:*"]
}

{
  "sid": "EverythingButIAM",
  "effect": "allow",
  "not_actions": ["iam:*"],
  "resources": ["*"]
}

not_actions with effect: allow grants every action the patterns do not name — including actions that do not exist yet, added by services shipped after the policy was written. Pairing exclusion with deny carves a hole out of a broad allow and has no such surprise. Prefer that.

Conditions

A condition compares a context key against values using an operator. Every condition on a statement must hold for it to apply.

{
  "effect": "allow",
  "actions": ["compute:*"],
  "resources": ["*"],
  "conditions": [
    { "operator": "ip_address", "key": "basalt:SourceIp", "values": ["203.0.113.0/24"] }
  ]
}

Operators

Operator	Holds when
`equals` / `not_equals`	The value matches / does not match any listed value
`starts_with` / `ends_with` / `contains`	Substring comparison
`in` / `not_in`	Membership in the list
`greater_than` / `less_than`	Numeric comparison
`greater_than_or_equals` / `less_than_or_equals`	Numeric comparison, inclusive
`exists` / `not_exists`	The key is present / absent
`ip_address` / `not_ip_address`	The address falls inside / outside the listed CIDRs

What happens when the key is missing

This is the part that decides whether a guardrail works, so it is worth being precise about.

A condition whose context key is absent from the request fails — except for the negated operators, which hold.not_equals, not_in, not_ip_address and not_exists are satisfied by a request that does not carry the key at all. Every other operator asserts something positive about a value that is not there, so it fails closed.

The reason is that a deny needs to fire on the request it is guarding against. “Deny unless the request comes from these addresses” has to catch a request with no address — treating the missing key as no match would make the guardrail fail open exactly when it matters.

Multi-valued keys

Some context keys are sets rather than single values — basalt:TagKeys is the set of tag keys a request carries. To compare against one, add a set_operator:

{
  "sid": "OnlyApprovedTagKeys",
  "effect": "deny",
  "actions": ["*"],
  "resources": ["*"],
  "conditions": [{
    "operator": "not_in",
    "set_operator": "for_all_values",
    "key": "basalt:TagKeys",
    "values": ["env", "owner", "cost-center"]
  }]
}

{
  "sid": "MustCarryEnvTag",
  "effect": "allow",
  "actions": ["compute:CreateInstance"],
  "resources": ["*"],
  "conditions": [{
    "operator": "equals",
    "set_operator": "for_any_value",
    "key": "basalt:TagKeys",
    "values": ["env"]
  }]
}

for_all_values holds when every member of the request set satisfies the operator. An absent or empty set holds vacuously — a request carrying no tags is not fenced by a tag-key restriction.
for_any_value holds when at least one member does. An absent or empty set does not hold.

Context keys

Key	Carries
`basalt:SourceIp`	The address the request came from. Supplied on every request.
`basalt:RequestTag/<key>`	The value of a tag being set by this request.
`basalt:ResourceTag/<key>`	The value of a tag already on the resource.
`basalt:TagKeys`	The set of tag keys the request carries. Multi-valued.

The two tag prefixes answer different questions. ResourceTag fences access to things already labelled a certain way; RequestTag fences what a caller is allowed to label something as.

Worked examples

Read-only across a service

{
  "version": "2024-01-01",
  "statements": [{
    "sid": "ReadOnlyCompute",
    "effect": "allow",
    "actions": ["compute:List*", "compute:Get*", "compute:Describe*"],
    "resources": ["*"]
  }]
}

Confine a team to one environment by tag

Reaches only resources already tagged env=staging:

{
  "version": "2024-01-01",
  "statements": [{
    "sid": "StagingOnly",
    "effect": "allow",
    "actions": ["compute:*", "storage:*"],
    "resources": ["*"],
    "conditions": [
      { "operator": "equals", "key": "basalt:ResourceTag/env", "values": ["staging"] }
    ]
  }]
}

This grants nothing on an untagged resource: equals on a missing key fails. That is usually what you want — an unlabelled resource is not quietly in scope.

Force new resources to be labelled correctly

A caller may create instances only while tagging them env=staging:

{
  "version": "2024-01-01",
  "statements": [{
    "sid": "CreateOnlyAsStaging",
    "effect": "allow",
    "actions": ["compute:CreateInstance"],
    "resources": ["*"],
    "conditions": [
      { "operator": "equals", "key": "basalt:RequestTag/env", "values": ["staging"] }
    ]
  }]
}

Fence an office network, and mean it

{
  "version": "2024-01-01",
  "statements": [{
    "sid": "DenyOffNetwork",
    "effect": "deny",
    "actions": ["*"],
    "resources": ["*"],
    "conditions": [
      { "operator": "not_ip_address", "key": "basalt:SourceIp", "values": ["203.0.113.0/24"] }
    ]
  }]
}

Written as a deny with the negated operator, so it also fires on a request that carries no source address. The inverse — allow when ip_address matches — leaves the fence off whenever the key is absent.

A guardrail that survives broad grants

{
  "version": "2024-01-01",
  "statements": [{
    "sid": "NeverTouchProdCerts",
    "effect": "deny",
    "actions": ["certificate:DeleteCertificate", "certificate:RevokeCertificate"],
    "resources": ["crn:certificate::my-account:certificate/prod-*"]
  }]
}

Attach it anywhere in the principal’s set. An explicit deny is not overridden by an Administrator allow.

Let a data-plane agent read one certificate's key

{
  "version": "2024-01-01",
  "statements": [{
    "sid": "MaterialForEdge",
    "effect": "allow",
    "actions": ["certificate:GetCertificateMaterial"],
    "resources": ["crn:certificate::my-account:certificate/edge-*"]
  }]
}

GetCertificateMaterial is a separate action from reading a certificate, precisely so this can be granted narrowly. See certificates.

Managed and inline policies

Managed policy

A standalone object with its own CRN. Account policies attach to roles and service accounts; organization policies also attach to users and groups. Edit once, and every attachment uses the updated document.

Inline policy

Written directly onto one principal, named rather than identified, and deleted with it. For a one-off grant that should never be reused or accidentally attached elsewhere.

An account managed policy is created on iam.basaltic.sh. Organization policies use the same collection path on workspace.basaltic.sh:

Console
API
CLI
Go

Open Identity & access → Policies and choose Create Policy for an account policy. Use Organization → Organization policies for an organization policy. Policy Document supports visual and JSON editing. Attach the saved policy from the appropriate identity page.

POST /v1/policies
{ "name": "S3ReadOnly", "document": { "version": "2024-01-01", "statements": [...] } }

basaltic iam policy create --name S3ReadOnly --document @policy.json

--document takes the JSON inline or @file; --from-file sends the whole request body instead.

p, err := iam.New(cfg).CreatePolicy(ctx, &iam.PolicyCreateRequest{
    Name:     "S3ReadOnly",
    Document: doc,
})

Inline policies live under the principal. This user example uses Workspace and an organization policy document:

Console
API
CLI
Go

Every user, group, service account and role has an Inline Policies card with Add Inline Policy — a Name and a Policy Document JSON editor. The name identifies the policy, so it is fixed once saved and editing one changes only the document.

PUT    /v1/users/{user_id}/inline-policies/{policy_name}
GET    /v1/users/{user_id}/inline-policies
DELETE /v1/users/{user_id}/inline-policies/{policy_name}

basaltic workspace user set-inline-policy <user-id> <policy-name> \
  --document @policy.json
basaltic workspace user list-inline-policies <user-id>
basaltic workspace user delete-inline-policy <user-id> <policy-name>

Account iam service-account and iam role, and organization workspace group, carry equivalent inline-policy operations.

c := workspace.New(cfg)
err := c.PutUserInlinePolicy(ctx, userID, "deny-billing-change", &workspace.PutInlinePolicyRequest{
    Document: doc,
})
list, err := c.ListUserInlinePolicies(ctx, userID)
err = c.DeleteUserInlinePolicy(ctx, userID, "deny-billing-change")

The user and group routes use Workspace and organization policy documents. The service account and role routes use IAM and account policy documents. Some managed policies are system policies, marked is_system. They are maintained by the platform, shared across organizations, and cannot be edited — attach them or don’t. The console badges them System rather than Custom and opens them as View Policy, with no save.

Validation

A document is rejected on save, not silently ignored, when:

version is missing or is not 2024-01-01
statements is empty
effect is not allow or deny
a statement sets both actions and not_actions, or neither
a statement sets both resources and not_resources, or neither
a condition has no key, or an unrecognised operator or set_operator

An unrecognised operator in a stored document — one saved before an operator was renamed, say — never matches. On an allow statement it is skipped; on a deny it is treated as a hard deny when the action and resource match, so a broken guardrail fails closed rather than open.

Permission boundaries

Capping what these policies can ever grant.

Roles and credentials

Session policies scope credentials down the same way.

Resource references

Policy, role and group names are immutable. Relationship fields such as policy, role, group and groups[] accept a UUID, a name or a CRN. The syntax selects the lookup; a missing resource never triggers a second lookup using another interpretation. Account policies use crn:iam::<account-handle>:policy/<name>. System account policies use crn:iam:::policy/<Name>. A bare name prefers a policy in the selected account, then a system policy. A fully qualified system CRN selects that namespace even when a custom policy has the same name. Organization policies use crn:workspace:::policy/<name>; system organization policies use crn:workspace:::system-policy/<Name>. An organization policy lookup does not search account policies, or vice versa. Roles use crn:iam::<account-handle>:role/<name>. Groups use crn:workspace:::group/<name>. Delegated organization policy attachment requests use the policy UUID in policy_id; see Workspace permissions. Lists with name and crn filters apply both before pagination. An empty value is still a filter. A foreign or mismatched CRN returns an empty page. See resource references for each list’s filters.

Get started

Products

Platform

Help

Choose the policy scope

Statements

Actions

Resources

Naming by exclusion

Conditions

Operators

What happens when the key is missing

Multi-valued keys

Context keys

Worked examples

Managed and inline policies

Managed policy

Inline policy

Validation

Next

Permission boundaries

Roles and credentials

Resource references

​Choose the policy scope

​Statements

​Actions

​Resources

​Naming by exclusion

​Conditions

​Operators

​What happens when the key is missing

​Multi-valued keys

​Context keys

​Worked examples

​Managed and inline policies

Managed policy

Inline policy

​Validation

​Next

Permission boundaries

Roles and credentials

​Resource references

Choose the policy scope

Statements

Actions

Resources

Naming by exclusion

Conditions

Operators

What happens when the key is missing

Multi-valued keys

Context keys

Worked examples

Managed and inline policies

Validation

Next

Resource references