Authorization

The model

Atom answers one question: can subject S perform action A on object O?

Subject gets a Role.
Role contains Permission Blocks.
Direct Policy gives a Subject one Permission Block directly.
Permission Block is the only place where scope and actions are defined.

Every new tenant (Workspace) gets a seeded tenant-admin role with the full administrative permission set — the successor to the old built-in admin role.

Decision flow

Deny-by-default, deny-overrides-allow:

1. Load the subject and the object being acted on.
2. Resolve the action and validate it's applicable to that object kind/type.
3. Collect the subject's role assignments and direct policies (expanding principal group membership).
4. Evaluate every matching Permission Block.
5. Any matching deny → Deny, full stop, regardless of any allow.
6. Otherwise, any matching allow → Allow.
7. No match at all → Deny (the default).

Permission Block shape

This is what Magistrala's Go code sends/receives:

type PermissionBlock struct {
	ID         string
	TenantID   string
	ScopeMode  string
	ObjectKind string // e.g. "entity", "resource", "group", "tenant", "role", "policy"
	ObjectType string // namespaced, e.g. "resource:rule", "resource:invoice"
	ObjectID   string // set only for an exact-object scope
	GroupID    string // set only for group-scoped modes
	Effect     string // "allow" or "deny"
	Conditions map[string]any // ABAC, {} for unconditional
	Actions    []Capability
}

ScopeMode is one of nine values: the tenant itself; all objects of a kind; all objects of a type; one exact object (by ObjectKind/ObjectType/ObjectID); an object group itself; direct objects in a group; objects in subgroups; direct child groups; or descendant groups.

DirectPolicy (one Permission Block → one subject) and GroupGrant (one Permission Block → every member of a principal group, present and future) are the two ways a block actually reaches a subject without going through a named Role — both also transcribed directly from pkg/atom/types.go.

How Magistrala services check authorization

Every service that needs an authorization decision — including the Enterprise alarms, reports, and re (Rules Engine) services — asks Atom the same shape of question Magistrala's own Go types describe:

type AuthzRequest struct {
	SubjectID  string
	Action     string
	ResourceID string
	ObjectKind string
	ObjectID   string
	Context    map[string]any
}

type AuthzResponse struct {
	Allowed bool
	Reason  string
}

The Enterprise services observed use ObjectKind = "resource" with a namespaced ObjectType like resource:rule — consistent with Atom's generic object-kind model above, not a bespoke per-service schema. The publicly-runnable equivalent is the CLI:

magistrala-cli authz check <subject_id> <action> --object-kind <kind> --object-id <id> --token <token>

(see the Authz CLI — the only authorization-related CLI command; there is no CLI for managing Roles/Permission Blocks/Direct Policies themselves, which are administered through Atom directly.)