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.

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, everywhere.

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:iam:::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 any allow, including an organization owner’s implicit access.

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, attached to any number of users, groups, service accounts and roles. Edit once, everywhere it is attached changes. This is the default choice.

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.

Inline policies live under the principal:

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}

The same four routes exist for service-accounts, roles and groups. 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.

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.

Get started

Products

Platform

Help

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

​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

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