Write your first policy

The policies Flowion provides cover the common cases. When they don't fit, write your own: a permission policy that allows exactly the permissions you name, for the hours you choose, and nothing else. Then give it to a member the way you would give them any policy, and ask the API why they can or can't do something.

This page makes three: a bookkeeper who sees and manages billing and nothing else, a morning shift that can send commands to chargers only on weekdays, and a deny that takes one thing away. For how policies, bindings and the provided policies fit together, read Permissions and policies first.

Before you start

• You need identity.policy.manage. The Owner holds it. Nobody else does until an Owner gives it to them, and a deny can never take it away from an Owner.

• A policy can only allow what you hold. To write a policy that allows billing.account.manage, you must hold it yourself, in this organization. A policy that goes further is refused with permission_policy.not_grantable. Every example below is for an Owner.

• Permission names are exact. There are no wildcards, so a policy never gains a permission by accident when a new one is added. Read the names from List permissions.

• $MEMBER is the membership id from GET /organizations/$ORG/members, not the user id.

Give a bookkeeper billing and nothing else

A policy is a name and a document. The document is version 1 and a list of statements. Each statement says allow or deny and names the permissions it covers.

curl -X POST "$API/organizations/$ORG/permission-policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bookkeeper",
    "document": {
      "version": 1,
      "statements": [
        {
          "effect": "allow",
          "permissions": ["billing.account.read", "billing.account.manage"]
        }
      ]
    }
  }'

{
  "id": "5d0c8a62-1f3e-4b7a-9c41-2e8f6a0b7d13",
  "name": "Bookkeeper",
  "kind": "custom",
  "version": 1,
  "permissions": ["billing.account.manage", "billing.account.read"],
  "document": {
    "version": 1,
    "statements": [
      {
        "effect": "allow",
        "permissions": ["billing.account.read", "billing.account.manage"]
      }
    ]
  },
  "createdAt": "2026-10-04T08:12:31Z",
  "updatedAt": "2026-10-04T08:12:31Z"
}

Keep the id: it is the policyId you give to a member.

curl -X POST "$API/organizations/$ORG/members/$MEMBER/bindings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policyId": "'"$BOOKKEEPER_POLICY"'"}'

Leaving out projectId gives the policy across the whole organization, which is where billing lives. The bookkeeper still holds what every member holds, and can now see and manage the organization's billing. They can't invite people, make API keys or touch a charger, because nothing allows it. Nothing is allowed unless a policy says so.

Change your mind later with Replace a permission policy. The version goes up and everyone who holds the policy holds the new document on their very next request.

Ask why: explain

Don't guess what a member can do. Ask. Explain runs the same code that answers every request, so it can't disagree with what really happens. It needs identity.policy.explain.

curl -X POST "$API/organizations/$ORG/permission-policies/explain" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberId": "'"$MEMBER"'", "permission": "billing.account.manage"}'

{
  "permission": "billing.account.manage",
  "resource": {
    "organizationId": "9b2e4c10-7a35-4d68-8f21-3c5d0e6a1b94",
    "mode": "live"
  },
  "verdict": "allow",
  "reason": "allowed",
  "decidedBy": {
    "policy": {
      "id": "5d0c8a62-1f3e-4b7a-9c41-2e8f6a0b7d13",
      "name": "Bookkeeper",
      "version": 1
    },
    "node": { "kind": "organization", "id": "9b2e4c10-7a35-4d68-8f21-3c5d0e6a1b94" },
    "statementIndex": 0,
    "effect": "allow"
  },
  "considered": [
    {
      "policy": {
        "id": "5d0c8a62-1f3e-4b7a-9c41-2e8f6a0b7d13",
        "name": "Bookkeeper",
        "version": 1
      },
      "node": { "kind": "organization", "id": "9b2e4c10-7a35-4d68-8f21-3c5d0e6a1b94" },
      "skippedForMode": false,
      "readable": true,
      "statements": [
        { "index": 0, "effect": "allow", "matched": true, "ignoredOwnerFloor": false }
      ],
      "warnings": [],
      "narrowsAssistant": false
    }
  ],
  "warnings": []
}

(considered is shortened here: it also lists every other policy the member holds.) Read it in this order:

• verdict is allow or refuse.

• reason says why. allowed and denied name a statement. For a refusal, no-allow-found means no policy allows it. The others are listed in Errors, pagination and versioning.

• decidedBy is the statement that decided: which policy, at which organization or project, and the statement's position (statementIndex counts from 0). It is absent when nothing decided, because nothing allowed it.

• considered is every policy that applied, with each statement and, for one that didn't match, the condition that stopped it: permission, mode, timeWindow or attributes.

Ask about something the bookkeeper may not do and you get the other half:

curl -X POST "$API/organizations/$ORG/permission-policies/explain" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberId": "'"$MEMBER"'", "permission": "identity.apikey.manage"}'

The answer is "verdict": "refuse" and "reason": "no-allow-found", with no decidedBy. Add "projectId" to ask about one project, "mode": "sandbox" to ask about sandbox, and "actingAs": "assistant" to ask about the member's assistant, which can do no more than the member and no more than read.

Limit a policy to a time of day

Add conditions to a statement to say when it applies. This morning shift can read and send commands to chargers (which includes starting and stopping a charge) from 06:00 to 11:00 on weekdays, on Stockholm time:

curl -X POST "$API/organizations/$ORG/permission-policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning shift",
    "document": {
      "version": 1,
      "statements": [
        {
          "effect": "allow",
          "permissions": ["ocpp.command.read", "ocpp.command.send"],
          "conditions": {
            "time_window": {
              "days": ["mon", "tue", "wed", "thu", "fri"],
              "from": "06:00",
              "to": "11:00",
              "zone": "Europe/Stockholm"
            }
          }
        }
      ]
    }
  }'

Give it at one project, so the shift reaches that site and no other:

curl -X POST "$API/organizations/$ORG/members/$MEMBER/bindings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policyId": "'"$SHIFT_POLICY"'", "projectId": "'"$PROJECT"'"}'

What a condition means:

Every condition in a statement must hold. There is no "or" inside a statement; write two statements instead.

Ask at 14:00 on a Tuesday and explain shows exactly what stopped it:

{
  "verdict": "refuse",
  "reason": "no-allow-found",
  "considered": [
    {
      "policy": { "name": "Morning shift", "version": 1 },
      "statements": [
        { "index": 0, "effect": "allow", "matched": false, "failedCondition": "timeWindow", "ignoredOwnerFloor": false }
      ]
    }
  ]
}

(Shortened to the relevant fields.)

Take something away with a deny

A deny beats any allow, from any policy, at the organization or in a project. Use one to keep a single permission away from someone who otherwise holds a lot:

curl -X POST "$API/organizations/$ORG/permission-policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "No key management",
    "document": {
      "version": 1,
      "statements": [
        { "effect": "deny", "permissions": ["identity.apikey.manage"] }
      ]
    }
  }'

Writing a policy that denies, and giving one, each needs identity.policy.deny as well, a separate right that only the Owner holds until they give it out. A deny can't name the few permissions only a transfer of ownership can move, such as identity.binding.manage: that is refused with permission_policy.deny_on_owner_floor, so an organization can't lock itself out of its own access.

Preview a change: simulate

Before you give or take a policy, see what it would change. Simulate decides every permission twice, under what the member holds now and under what they would hold, and returns the difference. It changes nothing.

curl -X POST "$API/organizations/$ORG/permission-policies/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "memberId": "'"$MEMBER"'",
    "add": [{"policyId": "'"$BOOKKEEPER_POLICY"'"}]
  }'

{
  "gained": ["billing.account.manage", "billing.account.read"],
  "lost": []
}

To preview taking something away, send the removeBindingIds you read from GET /organizations/$ORG/members/$MEMBER/bindings. Add projectId to evaluate at a project, and mode for sandbox. Conditions are weighed at the moment you ask, so a window that is closed now gains nothing yet.

When a policy is refused

A write that breaks a rule is refused with a code you can switch on, and the message says which statement:

The full list, with statuses, is in Errors, pagination and versioning.

Next: Errors, pagination and versioning.