API Usage Patterns

Practical integration patterns for public vs private APIs, plus a secure reference architecture for an MCP credential broker that serves local tools without exposing long-lived secrets.

Pattern

Public Client APIs

Use from web/mobile/extension clients with Firebase user tokens and per-user authorization.

Pattern

Private Automation APIs

Restrict to trusted server workloads. Enforce role requirements and tenant-bound scopes.

Pattern

MCP Credential Broker

Recommended model for app credential fetch with short-lived leases, policy checks, and strong auditability.

MCP Broker Authentication Model

Authenticate MCP workload identity (OIDC federation or mTLS).
Exchange workload identity or mint user API token for short-lived Aegis token (5-10 minute TTL).
Bootstrap local SPIFFE SVID via begin/complete challenge with CSR.
Send sender-constrained `request_proof` on each lease call (DPoP JWT or mTLS mode).
Apply policy gate on tenant, scope, and target application.
Issue short-lived credential lease (prefer lease over raw long-lived secret).
Write immutable audit event for every issuance/redeem/revoke action.

Token Management

Use short-lived broker access tokens (default 10m, cap 15m).
Keep bootstrap tokens narrower than broker lease scopes.
Rotate token material aggressively; avoid persistent local storage.
Require sender-constrained proofs for every lease action.
Use explicit revocation for compromised principals or PoP keys.

Scoped Credential Access

Scope must bind action and target resource selectors so the broker cannot redeem credentials outside policy.

credential.lease.create:provider:gcp:app:billing-prod:account:deploy-bot
credential.lease.redeem:provider:aws:app:payments:account:ci-role
credential.lease.revoke:provider:gcp:app:analytics:account:breakglass

Lease create/redeem/revoke calls require selector-scoped grants for the target app/account.
Action-only scopes (for example `credential.lease.create`) are not sufficient on their own.
User-minted tokens must use specific selectors and cannot use wildcard targets.

Recommended Token Claims

{
  "sub": "mcp:desktop-broker:host-01",
  "aud": "aegis-api",
  "tenant_id": "business-default",
  "scope": [
    "credential.lease.create:provider:gcp:app:billing-prod:account:deploy-bot",
    "credential.lease.redeem:provider:gcp:app:billing-prod:account:deploy-bot"
  ],
  "role": "org_admin",
  "jti": "8f7f9f5a-1ea8-4479-975f-5d716998a10f",
  "exp": 1762377600
}

Reference Flow

sequenceDiagram
  participant App as Local App
  participant MCP as MCP Server
  participant IdP as Workload Identity
  participant Aegis as Aegis API
  participant CA as SPIFFE CA
  participant Policy as Policy Engine
  participant Audit as Audit Log

  App->>MCP: Request credential for target
  MCP->>IdP: Authenticate workload
  IdP-->>MCP: Signed workload token
  MCP->>Aegis: ExchangeWorkloadToken (OIDC)
  MCP->>Aegis: BeginSpiffeBootstrap
  Aegis->>CA: Create one-time challenge
  CA-->>MCP: challenge_id + challenge_token + spiffe_id
  MCP->>Aegis: CompleteSpiffeBootstrap (CSR)
  Aegis->>CA: Sign SVID
  CA-->>MCP: X509 SVID chain + mtls_fingerprint
  MCP->>Aegis: ExchangeWorkloadToken (mTLS + fingerprint)
  Aegis->>Policy: Evaluate scope + target policy
  Policy-->>Aegis: allow / deny
  Aegis-->>MCP: Return short-lived lease
  MCP-->>App: Deliver lease / ephemeral secret
  Aegis->>Audit: Write immutable event

Hard Requirements

Private RPC callers must be trusted workloads. Do not call private endpoints directly from browser apps.
Keep production `ALLOW_INSECURE_USER_HEADER=false`.
Bind machine tokens to tenant and scope, and require explicit elevated role claims only where needed.
Use short token TTL, replay detection (`jti`), and proof-of-possession (DPoP or mTLS-bound tokens).
Continuously monitor and alert on anomalous issuance or access-denied spikes.

Docs Artifact

Full version is tracked in docs/api/usage-patterns.md.

Open API Explorer

Broker RPCs

Use `MintUserApiToken`, `ExchangeWorkloadToken`, `BeginSpiffeBootstrap`, `CompleteSpiffeBootstrap`, `CreateCredentialLease`, `RedeemCredentialLease`, `RevokeCredentialLease`, and `ListBrokerAuditEvents` for machine-to-machine credential brokerage.

Security Auth Model

Deep-dive guidance for workload authentication, sender-constrained tokens, replay protection, and incident response.

Open Security Model