Roles & scopes (SAP BTP)

Boidra Platform uses SAP BTP XSUAA for sign-in and permissions. The BTP approuter authenticates people before the app loads, so there is no Boidra login page. What each person may do is decided by scopes, which XSUAA groups into roles.

Scopes

The backend checks scopes, never role names, so roles can be renamed or recombined without touching permissions.

Scope	Grants
Read	Every read (GET). Everyone has it.
AgentWrite	Register agents, edit their classification, probe A2A endpoints, create versions
CostWrite	Import cost objects, set P&L baselines, edit cost assignments
Submit for review	Submit an AI asset for review
Approve review	Approve an AI asset in review
PlatformAdmin	Environments, bindings, gateway keys, judge prompts and pricing

The exact identifiers of the two review scopes are defined in the app's security descriptor (xs-security.json).

Read is deliberately broad. A FinOps controller can open the trace behind a cost spike without needing a separate read permission for every page.

Roles

Four role templates compose the scopes for the four people who use the platform:

Role	Scopes	For
Agent Engineer	Read · AgentWrite · submit for review	People who build, register and submit agents, MCP servers and skills
FinOps Controller	Read · CostWrite	People who own AI spend, baselines and cost assignments
Platform Operator	Read · PlatformAdmin	People who run the platform: environments, keys, pricing, judges
Release Approver	Read · approve review	People who approve AI assets before they are deployed and published

Segregation of duties

Submitting for review and approving are never in the same role. An engineer submits an asset; someone else approves it. This is the answer to the auditor's first question. See How approval works.

A person can hold several roles; they get the union of everything those roles allow.

Assign roles in the BTP cockpit

Roles are assigned the standard BTP way: in your subaccount, open Security → Role Collections, and add users (or your identity provider's groups) to the role collection for each role. Boidra Platform ships one role collection per role template. People who hold no role see a "No roles assigned" message telling them which collection to request.

What people see

• The app adapts to the roles held. The navigation shows only what a person can use. Someone with two or more roles picks a workspace (Agent Engineering, FinOps, Platform Operations or Release Approval) when they sign in; someone with one role goes straight to their home page.
• Privileged buttons stay visible but disabled, with a tooltip naming the role required, for example "Approve — requires the Release Approver role", so people learn who to ask.
• Choosing a workspace changes where you land, never what you may do.

Enforcement

The server is the boundary; the UI only mirrors it.

• Every change (every non-GET route) declares the scope it needs. A request without that scope is refused with 403, and the response names the missing scope:

  { "error": "forbidden", "required": "CostWrite" }

• The audit log records who actually acted, taken from the signed-in user's XSUAA token, not a name the client supplies.

• Projects are a lens on which agents you look at; they never grant permissions. "Finance project, FinOps role" is a valid combination; a project alone gives no rights.

Local development

Without an XSUAA binding (a local run), the backend grants every scope, records the actor as dev@localhost, and logs a warning at startup. This only applies when no binding exists, so it cannot switch on in a BTP deployment, which always has one.