Federation

Endpoint reference for federated backends (HashiCorp Vault, AWS SM, Azure KV, GCP SM). For deep dive, see Federation Deep Dive.

Base path: /v1/federation/

GET /v1/federation/backends#

List configured backends.

Scope: federation:read.

POST /v1/federation/backends#

Configure a backend.

Body:

Example (HashiCorp):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "name": "hashicorp-production",
  "type": "hashicorp-vault",
  "config": {
    "endpoint": "https://vault.internal:8200",
    "auth_method": "approle",
    "auth_config_path": "infra/hashicorp/approle-creds",
    "tls_verify": true
  },
  "path_mapping": {
    "external/hashicorp/**": "secret/data/**"
  },
  "mode": "proxy"
}

Example (AWS):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "name": "aws-prod",
  "type": "aws-secrets-manager",
  "config": {
    "region": "us-east-1",
    "credentials_path": "infra/aws/sm/reader"
  },
  "path_mapping": {
    "external/aws/**": "prod/**"
  },
  "mode": "sync",
  "sync_interval": "15m"
}

Scope: federation:write.

GET /v1/federation/backends/{id}#

PATCH /v1/federation/backends/{id}#

DELETE /v1/federation/backends/{id}#

GET /v1/federation/backends/{id}/status#

Connection and sync status.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "id": "fed_abc",
  "name": "hashicorp-production",
  "status": "healthy",
  "last_sync": "2026-04-23T...",
  "last_sync_duration_ms": 3421,
  "secrets_synced": 127,
  "connection": {
    "status": "connected",
    "latency_ms": 15
  }
}

POST /v1/federation/backends/{id}/sync#

Trigger manual sync (for sync mode).

Scope: federation:write.

GET /v1/federation/backends/{id}/conflicts#

List sync conflicts (same path exists locally and remotely with different values).

Modes#

Proxy#

Reads pass through to the backend in real time. Writes to proxied paths are rejected (the backend is the source of truth).

Pros: always fresh. Cons: backend latency + availability impact every read.

Sync#

ScaiVault periodically pulls secrets from the backend into local storage. Reads hit local cache.

Pros: fast, resilient to backend outages. Cons: staleness up to sync_interval.

Related#

• Federation Deep Dive