EQTY LabDocs

Control Plane Authentication and RBAC

Bearer token modes, platform roles, agent bindings, project permissions, and API key limits in the Control Plane.

View as Markdown

Every authenticated Control Plane request carries Authorization: Bearer <token>. There is no browser sign-in or cookie session. GET /health is always public.

Bearer Modes

The Control Plane verifies bearer tokens in one of two modes:

  • Auth Service (auth_service): the mode a Guardian Platform deployment uses. The Control Plane forwards each token to Auth Service, which validates it and returns the user, their organization roles, and their claims. Results are cached for 30 seconds; an Auth Service outage is not cached and fails closed. The token is the one Guardian holds for the signed-in user, or an API key on the routes that accept keys.
  • OIDC (oidc): for a standalone gateway stack without Auth Service. The Control Plane verifies an OIDC ID token against the issuer’s keys and expected client ID. Tools discover the issuer and client from GET /v1/auth/device-config and sign in with the device flow. That route returns 404 in Auth Service mode.

Authentication can also be turned off for local development. Every request then acts as a platform admin, and registration tokens are minted for a fixed local subject, provided a registration token secret is set.

Platform Roles

  • Admin: full access to the agent registry, including user management, creating, revoking, and restoring agents, reading agent status events, and writing global plugin definitions, artifacts, secrets, configurations, and validation rules. In Auth Service mode an Organization Owner is an admin. In OIDC mode a user is an admin only through a stored user record with the admin role.
  • Member: every other signed-in user. A member sees only the agents they are bound to. A viewer binding lets them read an agent; an operator binding also lets them save its operating profile and attach certifications.

In Auth Service mode, the auditor who authorized a certification can also attach it to the agent, when its issuer is trusted.

The email domain allowlist, when configured, refuses tokens whose email is outside it on every route except the project-scoped routes for Guardian projects, which Auth Service authorizes. The one other exception is Governance Service’s service account, which can read an agent so it can check the agent is active before certifying it.

Project-Scoped Routes

Routes under /v1/projects/{project_uuid}/ follow the Guardian project with that UUID, not the agent binding. The Control Plane keeps no copy of projects: Auth Service checks the caller’s permission on the project, and results, denials included, are cached for 30 seconds. A project with nothing recorded on the gateway yet answers with empty results. Platform admin grants nothing extra here. GET /v1/projects lists the projects the caller can view, read from Auth Service, and display_name narrows it to one project by name.

ActionPermission on the Guardian project
Read project agents, their audit exchanges, state, and credentialsView Project Data
Read memberships, trust evidence, and plugin configurationsView Project Data
Submit membership evidenceEdit Project Settings
Validate, create, activate, or roll back a project plugin configurationEdit Project Settings
Submit trust evidenceCreate Credentials

These routes return only the records the gateway attributed to that project. A project the caller can’t act on returns 403 Forbidden, whether it doesn’t exist, belongs to another organization, or the permission is missing. An Auth Service outage returns 503 Service Unavailable. A platform admin needs these permissions too.

In Auth Service mode, minting a registration token requires Register Agents in the organization. The check is never cached. A denied permission returns 403, and an Auth Service outage returns 502 with auth_service_unavailable. A standalone deployment in OIDC mode lets any signed-in user mint.

API Keys

The Control Plane accepts an API key only on routes that ask Auth Service for a permission: registration tokens, the project-scoped routes above, and GET /v1/agents with project_uuid. Per-agent routes also accept a key with no project binding that has empty scopes or full access (*), which acts as its holder, or the scope for what the route does: submit_agent_assessments reads the agent, view_agent_certifications reads its certifications, and manage_programs or review_agent_assessments attach one. A scope counts only while the key’s holder still holds that permission in the key’s organization. A key never acts as an admin, even when its owner is one. Routes gated on identity alone, such as /v1/me, refuse keys with 403.

API Keys and Service Accounts lists every rule, including the view_agent_certifications scope for deploy automation.