How AgentBreeder handles identity, roles, asset permissions, approval workflows, and enterprise SSO integration.

Authentication & Authorization

AgentBreeder uses a layered security model: every user, team, and service principal gets a scoped identity, every asset has per-principal ACLs, and every deployment requires an approved state. Enterprise customers can plug in Okta, Azure AD, AWS IAM, or any SAML 2.0 provider.

Identity model

Org (agentbreeder instance)
 └── Teams  (engineering, data-science, ops, …)
      ├── Users           email + password  or  SSO identity
      ├── Service Principals  for CI/CD and machine-to-machine
      └── Groups          a named set of users (e.g. "ml-leads")

Every principal that joins a team is automatically issued a scoped LiteLLM virtual key that controls which models they can call and enforces their spending budget. The key is shown once at creation; AgentBreeder stores only the first 12 characters for display.

Platform roles

Roles exist at two scopes: platform (org-wide) and team (scoped to one team). A user can have different roles on different teams.

Role	Deploy assets	Approve requests	Manage teams	Manage billing
`admin`	✅	✅	✅	✅
`deployer`	✅	❌	❌	❌
`contributor`	submit only	❌	❌	❌
`viewer`	❌	❌	❌	❌

Least privilege by default

New users join as viewer. Admins promote them. Contributors can build and submit assets for approval but cannot deploy until an admin approves.

Asset permissions

Every asset (agent, prompt, tool, memory config, RAG index, knowledge base, model) carries its own access control list.

Default ACL on creation

Principal	read	use	write	deploy	publish	admin
Owner (creator)	✅	✅	✅	requires approval	✅	✅
Owner's team	✅	✅	❌	❌	❌	❌
Other teams	✅	❌	❌	❌	❌	❌
External / unauthenticated	❌	❌	❌	❌	❌	❌

Action definitions

Action	What it allows
`read`	View the asset's config, YAML, and metadata
`use`	Invoke the asset (call an agent, search a RAG index, run a tool)
`write`	Edit config, update YAML, create new versions
`deploy`	Push to a cloud target — requires approved state
`publish`	Share to the org-wide registry for others to discover
`admin`	Change the asset's ACL, transfer ownership

Granting access from the dashboard

Assets → [select asset] → Permissions → Add principal

Or via CLI:

agentbreeder acl grant \
  --asset agents/customer-support \
  --principal team:data-science \
  --actions read,use

agentbreeder acl grant \
  --asset prompts/support-system-v3 \
  --principal user:bob@company.com \
  --actions read,write

Approval workflow

Any contributor can build and submit assets. Deployment is gated by an admin approval.

Contributor creates / edits asset
         │
         ▼
  agentbreeder submit        (or dashboard → "Submit for Review")
         │
         ▼
  ApprovalRequest created    status: pending
  Admin group notified       (email + dashboard badge)
         │
         ├── Admin approves  → status: approved  → deployer can run agentbreeder deploy
         └── Admin rejects   → status: rejected  → contributor sees rejection reason

Every approval decision is written to the immutable audit log with: approver identity, timestamp, asset version, and free-text reason.

Submitting an asset

agentbreeder submit --asset agents/my-agent --message "Ready for prod review"

Approving from the dashboard

Governance → Approval Queue → [select request] → Review → Approve / Reject

Approving from the CLI (admin only)

agentbreeder review approve <request-id> --reason "LGTM, tested in staging"
agentbreeder review reject  <request-id> --reason "System prompt needs PII guardrail"

Admins bypass approval

Users with the admin platform role can deploy without submitting for approval. For regulated environments, disable this with require_approval_for_admins: true in your org settings.

LiteLLM virtual keys

Every team member and service principal gets a scoped virtual key that routes through the AgentBreeder LiteLLM gateway. Keys enforce:

Which models the principal can call
Per-day / per-week / per-month spending caps
Requests-per-minute and tokens-per-minute rate limits
Routing tags for cost attribution (e.g. team:engineering, agent:support-bot)

Key lifecycle

Event	Key action
User joins team	Key auto-minted with team defaults
Agent deployed	Agent-scoped key auto-minted during `registering` step
User removed from team	Key revoked
Key expires	Auto-revoked; new key issued on next login

Creating a custom key (admin)

agentbreeder key create \
  --scope team \
  --scope-id engineering \
  --models "claude-sonnet-4,gpt-4o" \
  --max-budget 50.00 \
  --budget-duration monthly \
  --tags production,rag

Enterprise SSO

Coming soon — not yet available

Enterprise SSO (Okta, Azure AD, AWS IAM, Google Workspace, SAML 2.0) is in development and not yet available. Tracked in GitHub issue #133. Until it ships, use local email + password authentication. The configuration reference below documents the planned API.

AgentBreeder will ship with a pluggable auth provider system. Set auth_provider in your org config to switch from local accounts to any of the following.

# .agentbreeder/org.yaml
auth_provider: okta
okta:
  domain: your-org.okta.com
  client_id: 0oa...
  client_secret: ${OKTA_CLIENT_SECRET}
  groups_claim: groups          # Okta group names → AgentBreeder teams
  admin_group: AgentBreeder-Admins

Okta groups are automatically mapped to AgentBreeder teams. Members of AgentBreeder-Admins receive the admin platform role.

auth_provider: azure_ad
azure_ad:
  tenant_id: ${AZURE_TENANT_ID}
  client_id: ${AZURE_CLIENT_ID}
  client_secret: ${AZURE_CLIENT_SECRET}
  # Optional: restrict to specific AD groups
  allowed_groups:
    - AgentBreeder-Users
    - AgentBreeder-Admins

auth_provider: aws_iam
aws_iam:
  # For EC2/EKS workloads — uses IMDS/pod identity, no secret needed
  role_arn: arn:aws:iam::123456789012:role/AgentBreeederServiceRole
  # Map IAM tags to AgentBreeder teams
  team_tag: agentbreeder:team
  role_tag: agentbreeder:role

Service principals (CI/CD, Lambda functions) authenticate via sts:AssumeRole. No passwords.

auth_provider: google
google:
  client_id: ${GOOGLE_CLIENT_ID}
  client_secret: ${GOOGLE_CLIENT_SECRET}
  hosted_domain: your-company.com   # restrict to this domain
  admin_group: agentbreeder-admins@your-company.com

auth_provider: saml
saml:
  idp_metadata_url: https://your-idp.com/metadata
  sp_entity_id: https://agentbreeder.your-company.com
  attribute_mapping:
    email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    groups: http://schemas.xmlsoap.org/claims/Group

Works with any SAML 2.0 compliant IdP: Ping Identity, OneLogin, ADFS, etc.

auth_provider: local   # default — email + password, bcrypt-hashed

Suitable for development and self-hosted deployments without an IdP. Not recommended for production multi-user environments.

VPN and network-level auth

AgentBreeder does not enforce VPN access itself — deploy it behind your existing VPN or zero-trust proxy (Cloudflare Access, Tailscale, AWS ALB with OIDC). The API will validate the JWT or SSO token from the upstream proxy.

Service principals

Service principals are non-human identities for CI/CD pipelines, automated scripts, and agent-to-agent calls.

Creating a service principal

# Creates a principal and prints the key once
agentbreeder principal create \
  --name "github-actions-deploy" \
  --team engineering \
  --role deployer \
  --allowed-assets "agents/*,prompts/*"

Using in CI/CD

# .github/workflows/deploy.yml
- name: Deploy agent
  env:
    AGENTBREEDER_API_KEY: ${{ secrets.AGENTBREEDER_DEPLOY_KEY }}
  run: agentbreeder deploy --target aws

The AGENTBREEDER_API_KEY is a long-lived service principal token. It is scoped to the team and role defined at creation — it cannot access assets outside its ACL.

RBAC REST API

All RBAC operations are available as a first-class REST API under /api/v1/rbac/. Every endpoint requires a valid JWT (Bearer token).

Permissions

GET    /api/v1/rbac/permissions                  # list ACL entries (filterable)
POST   /api/v1/rbac/permissions                  # grant a permission
DELETE /api/v1/rbac/permissions/{id}             # revoke a permission
GET    /api/v1/rbac/permissions/check            # check if caller can perform action

Grant a permission:

POST /api/v1/rbac/permissions
{
  "resource_type": "agent",
  "resource_id": "uuid-of-the-agent",
  "principal_type": "team",
  "principal_id": "data-science",
  "actions": ["read", "use"]
}

Check permission:

GET /api/v1/rbac/permissions/check?resource_type=agent&resource_id=<uuid>&action=deploy
→ { "allowed": true, "reason": "Direct user permission" }

Approval queue

GET    /api/v1/rbac/approvals                    # list pending/decided approvals
POST   /api/v1/rbac/approvals                    # submit an asset for approval
GET    /api/v1/rbac/approvals/{id}               # get approval detail
POST   /api/v1/rbac/approvals/{id}/approve       # approve (admin only)
POST   /api/v1/rbac/approvals/{id}/reject        # reject (admin only)

Service principals

GET    /api/v1/rbac/service-principals           # list all SPs
POST   /api/v1/rbac/service-principals           # create SP
GET    /api/v1/rbac/service-principals/{id}      # get SP detail
PUT    /api/v1/rbac/service-principals/{id}      # update SP
DELETE /api/v1/rbac/service-principals/{id}      # delete SP
POST   /api/v1/rbac/service-principals/{id}/rotate-key  # issue new key

Principal groups

GET    /api/v1/rbac/groups                       # list groups
POST   /api/v1/rbac/groups                       # create group
GET    /api/v1/rbac/groups/{id}                  # get group
PUT    /api/v1/rbac/groups/{id}                  # update group
DELETE /api/v1/rbac/groups/{id}                  # delete group
POST   /api/v1/rbac/groups/{id}/members          # add member
DELETE /api/v1/rbac/groups/{id}/members/{member_id}  # remove member

LiteLLM virtual keys

GET    /api/v1/rbac/keys                         # list keys (no secret values)
POST   /api/v1/rbac/keys                         # create key (value shown once)
DELETE /api/v1/rbac/keys/{id}                    # revoke key
GET    /api/v1/rbac/keys/{id}/reveal             # reveal full key value (admin only)

Audit log

Every auth and authorization event is written to the immutable audit log:

Event	Logged fields
Login (success/failure)	user, IP, provider, timestamp
Token issued	user, scope, expiry
Asset permission change	actor, asset, before, after
Approval decision	approver, asset, version, reason
Deploy	actor, asset, target, approval_id
Key created/revoked	actor, key_alias, scope

agentbreeder audit --asset agents/customer-support --since 7d
agentbreeder audit --user bob@company.com --action deploy

Self-hosted deployment checklist

Before going to production with a multi-user deployment:

Set auth_provider to your enterprise IdP (not local)
Set SECRET_KEY to a random 256-bit value (never the default)
Enable require_approval_for_admins: true for regulated environments
Configure team default spending budgets
Place the API behind your VPN or zero-trust proxy
Enable audit log export to your SIEM (Splunk, Datadog, CloudTrail)
Rotate service principal keys on a schedule (recommend 90 days)

Teams & Registry Guide — how teams own registry assets
CLI Reference: agentbreeder acl — full ACL command reference
CLI Reference: agentbreeder audit — querying the audit log
Agent YAML: access block — per-agent visibility and caller restrictions

Authentication & Authorization

On this page