REST API: Flow ACLs

Per-flow access control. List, grant, revoke.

All endpoints under /api/v1/flows/{flow_id}/acls. Require admin ACL on the target flow (or super_admin / tenant_admin).

Access levels (strict hierarchy)#

Higher levels imply lower ones — granting deploy automatically allows everything below it.

Implicit admin:

• The flow's owner (always; can't be removed).
• Super admin users (every flow).
• Tenant admin users (every flow in their tenant).

GET /v1/flows/{flow_id}/acls#

List explicit ACLs on this flow (the implicit owner/admin/tenant-admin grants aren't listed).

Response:

[
  { "id": "acl_xxx",
    "flow_id": "flow_abc123",
    "principal_type": "user",     // or "group"
    "principal_id": "usr_alice",
    "level": "edit",
    "granted_by": "usr_owner",
    "granted_at": "2026-04-29..." }
]

admin ACL on the flow.

POST /v1/flows/{flow_id}/acls#

Grant an ACL.

Body:

{
  "principal_type": "user",      // or "group"
  "principal_id": "usr_alice",
  "level": "edit"
}

Response: 201 Created with the new FlowACLOut.

admin ACL.

Errors:

• 400 — invalid level, unknown principal_type.
• 404 — principal_id doesn't exist in the local user/group mirror. (Run a sync first or use a valid id.)
• 409 — an ACL with the same principal already exists; PATCH instead, or delete + re-create.

DELETE /v1/flows/{flow_id}/acls/{acl_id}#

Revoke an ACL. 204 No Content.

admin ACL.

Refuses to revoke the implicit owner ACL — change ownership via super_admin if you need to remove the owner.

Patterns#

"Everyone in my tenant can view"#

Don't add a group ACL for the tenant's all-users group — that's what scaicore:view + the flow's tenant scope already does at the permission level. Instead, leave the flow with no group ACLs and let tenant membership do the work.

For tighter scoping (only some users in the tenant), use a smaller group:

{ "principal_type": "group", "principal_id": "grp_acme_eng", "level": "view" }

"Bob can edit, Alice can deploy"#

{ "principal_type": "user", "principal_id": "usr_bob", "level": "edit" }
{ "principal_type": "user", "principal_id": "usr_alice", "level": "deploy" }

"All engineers can deploy, all PMs can view"#

{ "principal_type": "group", "principal_id": "grp_eng", "level": "deploy" }
{ "principal_type": "group", "principal_id": "grp_pm", "level": "view" }

A user in both groups gets the highest applicable level (deploy in this case).

"Pin a flow to one person"#

Just don't add any ACLs. The owner has implicit admin and nobody else has access (unless they're a tenant admin or super admin).