BoscaDeveloper Documentation

Permissions

Grant actions to groups, filter readable records, and check authority before a write.

Permissions are granted to security groups. A principal receives access through its group memberships, including its personal group. Organization membership does not automatically grant access to content. Domain-specific evaluators can add rules to the shared behavior below.

PermissibleEntity

kotlin

PermissionAction

ActionPurpose
VIEWSee the entity exists and read its fields
LISTList an entity or its items, as defined by the owning API
EDITModify the entity
MANAGEGrant/revoke permissions (implies EDIT)
DELETESoft-delete the entity
EXECUTEExecute an operation such as a script, job, or workflow transition
IMPERSONATEAct as another principal in this context

The Decision Chain

When isAllowed(authentication, entity, action) is called:

  1. Deleted check — access to deleted records requires hasSaGroup(), which accepts SA or administrators with the required token scope.
  2. Public access — if public and published/advertised, VIEW is granted. If publicList and published/advertised, LIST is granted.
  3. Token scopes — private access and writes through scoped API tokens must satisfy the evaluator's domain scope rules. Public reads remain independently accessible.
  4. Editor group — the shared evaluator grants EDIT through hasEditorGroup(); domain evaluators can impose additional rules.
  5. Entity-level permissions — checks user's groups against EntityPermission records. MANAGE also satisfies EDIT.
  6. Role-based fallback — the shared evaluator accepts SA and administrators for all actions. Editors and managers satisfy actions other than MANAGE, EXECUTE, and IMPERSONATE, subject to scope checks.
  7. Parent access — if no earlier rule allows access, the owning permission service evaluates inherited access through isParentAllowed().

Published vs. Advertised

Advertised is a "soft-public" state — the entity can be found and viewed, but its binary content and supplementary attachments remain restricted.

WhatRequired FlagRequired State
Entity record (title, description)public = truepublished or advertised
Entity in list/search resultspublicList = truepublished or advertised
Binary content (file download)publicContent = truepublished only
Supplementary attachmentspublicSupplementary = truepublished only

In Queries: Filter, Don't Throw

Query fields silently filter unauthorized data to avoid leaking information:

kotlin
Public query resolvers can accept an unauthenticated context and return only accessible data. Administrative queries require explicit group or permission checks. Parameter nullability alone does not authorize a request.

In Mutations: Verify and Throw

kotlin

Creating New Entities

When creating, check permissions on the parent or require a group:

kotlin

GroupEvaluator

For operations that don't target a specific entity:

kotlin

Locked Entities

Collection controllers restrict edits to locked records using hasSaGroup(), which accepts SA or administrators with the required scope:

kotlin