Skip to content

Credential Management

Lucid uses an MCP-first credential model: agents access external services exclusively via MCP tools, and credentials are managed through a three-tier inheritance cascade (org → workspace → agent). There is no per-agent raw credential storage — credentials are created once at the org or workspace level and selectively pushed down to agents with configurable sharing and enforcement policies.

Core Concepts

ScopedCredential

A ScopedCredential holds a service credential (OAuth token, API key, or OAuth flow result) at the org or workspace level. Rather than storing credentials per-agent, a credential is created once at a higher scope and inherited or enforced downward.

Each credential has a sharing mode that controls how it cascades:

Mode Behavior
inherit Child scopes (workspace or agent) receive the credential as a default. They can supplement or override it by connecting their own.
enforce Child scopes must use this credential. When an agent installs the matching MCP tool, OAuth DCR is skipped and this credential is used automatically. Agents cannot connect a different one.
isolated Credential is not shared with child scopes. Only the scope that created it uses it.

ScopedToolInstall

A ScopedToolInstall records that an MCP tool has been installed at the org or workspace scope and specifies a tool enforcement policy that cascades to agents:

Enforcement Behavior
available Tool is offered to agents but not required. Agents can install or skip it freely.
required All agents in scope must have this tool. The wizard pre-installs it and agents cannot remove it.
blocked Tool is forbidden for all agents in scope. The wizard hides it and manual installation is rejected.

Three-Tier Cascade

Org Level
  ├── ScopedToolInstall  (available / required / blocked)
  └── ScopedCredential   (inherit / enforce / isolated)
          │
          ▼
  Workspace Level
    ├── ScopedToolInstall  (refines org policy or adds workspace-only tools)
    └── ScopedCredential   (inherit / enforce / isolated)
              │
              ▼
          Agent Level
            └── Tool install via wizard
                  (blocked by org/ws policy, pre-filled if enforced, or free choice)

The /v1/scoped-tools/effective and /v1/scoped-credentials/effective endpoints resolve the full cascade for a given agent, returning which tools are available/required/blocked and which credential applies for each service.

Three Auth Models

Credentials map to three auth models. The right model depends on who the agent is acting as:

Model Name Credential Type When
1 Autonomous Identity Agent's own SPIFFE-SVID / OAuth client Cron jobs, A2A calls, self-acting MCP tools
2 OBO Delegation RFC 8693 composite token (sub = human, act = agent) "Search my email", "Send as me" — acts on behalf of a specific user
3 Provisioned Credentials ScopedCredential (OAuth token or API key) Shared API keys, org-level service accounts, third-party integrations

Each CredentialRoutingRule has an injection_method that selects the model:

injection_method Auth Model Sidecar Behavior
client_credentials Model 1 Sidecar uses agent's SPIFFE-SVID to obtain a token from the MCP server's AS
token_exchange Model 2 Sidecar performs RFC 8693 exchange combining user token + agent SVID
sidecar Model 3 Sidecar injects the stored ScopedCredential into the outbound request

Connecting Credentials

Via the Observer UI

Credentials are connected through the Integrations wizard in Observer:

Scope Navigation
Org Settings → Organization → Integrations
Workspace Workspace Settings → Integrations
Agent Agent page → Integrations → "+ Add Tool"

The wizard walks through:

  1. Browse the MCP tool catalog and select a tool.
  2. Authenticate — either OAuth popup or API key entry.
  3. Choose a sharing mode (for org or workspace scopes): inherit, enforce, or isolated.
  4. Save. The credential is encrypted server-side; the agent runtime never sees the raw value.

When an agent installs a tool later, the wizard checks for an existing enforced credential and skips the Connect step if one applies.

Via YAML

Credential routing can also be declared in the workspace YAML definition:

environment:
  credentialRouting:
    - destination: "*.slack.com"
      injectionMethod: token_exchange    # OBO — acts as the user
      ttl: 15m
    - destination: "api.github.com"
      credentialRef: github-oauth        # Resolves to a ScopedCredential by name
      injectionMethod: sidecar
      ttl: 1h
    - destination: "mcp.internal.example.com"
      injectionMethod: client_credentials  # Agent's own SPIFFE identity
      ttl: 1h

MCP Tool Install Flow

When an agent installs an MCP tool from the catalog, the platform runs this sequence:

  1. Policy check — If the tool is blocked at org or workspace scope, install is rejected immediately.
  2. Credential inheritance — If the tool's service has a ScopedCredential with sharing_mode: enforce at org or workspace scope, that credential is applied automatically. OAuth DCR is skipped; a CredentialRoutingRule pointing to the inherited credential is created.
  3. RFC 9728 discovery — If no enforced credential applies, Lucid fetches the MCP server's /.well-known/oauth-protected-resource (RFC 9728). If auth metadata is found, the agent is auto-registered as an OAuth client via RFC 7591 (Dynamic Client Registration), and a CredentialRoutingRule with injection_method: client_credentials is created automatically.
  4. Manual connect — For MCP servers without RFC 9728 metadata (or when the user wants to supply a specific API key), the wizard opens the Connect dialog.
flowchart TD
    A[Agent installs MCP tool] --> B{Tool blocked at\norg or workspace?}
    B -- Yes --> C[Reject install]
    B -- No --> D{Enforced credential\nfor this service?}
    D -- Yes --> E[Apply inherited credential\nSkip DCR]
    D -- No --> F{MCP server exposes\nRFC 9728 metadata?}
    F -- Yes --> G[Auto-register via RFC 7591\nCreate CredentialRoutingRule\nclient_credentials]
    F -- No --> H[Open Connect dialog\nOAuth popup or API key]

API Reference

Scoped Credentials

GET    /v1/scoped-credentials?scope=org&scope_id={id}     # List credentials at a scope
POST   /v1/scoped-credentials                              # Create a credential
DELETE /v1/scoped-credentials/{id}                         # Revoke a credential
GET    /v1/scoped-credentials/effective?agent_id={id}      # Resolve cascade for an agent

Scoped Tools

GET    /v1/scoped-tools?scope=workspace&scope_id={id}      # List tool installs at a scope
POST   /v1/scoped-tools                                    # Install a tool at org/ws scope
DELETE /v1/scoped-tools/{id}                               # Remove a tool install
GET    /v1/scoped-tools/effective?agent_id={id}            # Resolve cascade for an agent

Credential values are never returned in list or detail responses — only metadata (service name, sharing mode, auth status, created_at).

  • VAP Guide — Agent identity, the three auth models, delegation grants, and MCP server auth discovery
  • MCP — How MCP tool federation works and the RFC 9728/7591 discovery flow
  • Verifier API — Full endpoint reference for scoped-credentials and scoped-tools
  • Glossary — ScopedCredential, ScopedToolInstall, SharingMode, ToolEnforcement definitions