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.

Asset permissions

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

Default ACL on creation

Action definitions

Granting access from Studio

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 Studio → "Submit for Review")
         │
         ▼
  ApprovalRequest created    status: pending
  Admin group notified       (email + Studio 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 Studio

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"

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

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

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

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

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

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

First-login password rotation

The seeded admin account ships with the publicly documented credential admin@agentbreeder.local / plant. To prevent a known-credential takeover on any install exposed beyond localhost, every fresh install is flagged with must_change_password=true on the seed admin row.

What this means in practice:

• Studio intercepts the first sign-in: instead of routing to the home page, the user lands on /change-password with a non-dismissable form. They must set a password that is at least 8 characters and differs from the current one. Sign-out is the only escape hatch.
• CLI (agentbreeder login) detects the flag on the login response and prompts for a new password before persisting the token to the OS keychain. A token tied to the default plant credential never lands on disk.
• The flag clears on the user row as soon as the rotation succeeds; subsequent sign-ins behave normally.

Admins can force a rotation on any user by setting the column directly in the database:

UPDATE users SET must_change_password = TRUE WHERE email = 'alice@example.com';

The next time Alice signs in (Studio or CLI), she will be walked through the rotation flow before doing anything else.

Wire format

POST /api/v1/auth/login returns:

{
  "data": {
    "access_token": "eyJ...",
    "token_type": "bearer",
    "must_change_password": true
  }
}

Clients that see must_change_password: true should call POST /api/v1/auth/change-password with {"old_password": "...", "new_password": "..."} before any other authenticated request. The endpoint returns the refreshed UserResponse with the flag cleared.

The flag is currently a client-side nudge — the API still issues working tokens to flagged accounts so programmatic admin setup paths (like agentbreeder quickstart) continue to work. Server-side enforcement is tracked separately.

CLI login

The CLI authenticates against the same POST /api/v1/auth/login endpoint that Studio uses. Tokens live in the OS keychain (macOS Keychain, GNOME libsecret, Windows Credential Manager) via the keyring library — you never have to copy a JWT into a shell env var by hand.

Logging in

# Interactive — prompts for email and (hidden) password
agentbreeder login

# Non-interactive
agentbreeder login --email alice@example.com --password "$AB_PASSWORD"

# Or paste a token issued by Studio
agentbreeder login --token "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

On success the token is written to the OS keychain. Subsequent commands (agentbreeder whoami, agentbreeder registry agent list, …) pick it up automatically.

whoami

agentbreeder whoami
# email           alice@example.com
# name            Alice Example
# role            deployer
# team (primary)  engineering
# active team     ops
# id              5b3e9c…

agentbreeder whoami --json | jq .role

Logging out

agentbreeder logout
# Logged out.

logout deletes the keychain entry. It does not revoke the token server-side — the JWT remains valid until its expiry (24h by default). For server-side revocation see refresh-token issue #395.

Active team context

If your account belongs to multiple teams, set the one you want to act as:

agentbreeder context use ops      # subsequent calls send X-AgentBreeder-Team: ops
agentbreeder context show
agentbreeder context clear        # falls back to your primary team

The active team is stored in ~/.agentbreeder/context.json and is sent on every authenticated request as the X-AgentBreeder-Team header.

CI / non-interactive use

In CI you typically don't have a keychain. Export AGENTBREEDER_API_TOKEN directly:

- run: agentbreeder registry agent list
  env:
    AGENTBREEDER_API_TOKEN: ${{ secrets.AGENTBREEDER_DEPLOY_KEY }}
    AGENTBREEDER_URL: https://api.example.com

The env var always wins over the keychain, so the same CLI binary works for laptops and CI without code changes.

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:

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)

Related

• 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