---
title: Federation
path: reference/federation
status: published
---

# Federation Reference

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

**Base path:** `/v1/federation/`

## GET /v1/federation/backends

List configured backends.

**Scope:** `federation:read`.

## POST /v1/federation/backends

Configure a backend.

Body:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | |
| `type` | Yes | `hashicorp-vault`, `aws-secrets-manager`, `azure-key-vault`, `google-secret-manager` |
| `config` | Yes | Backend-specific |
| `path_mapping` | Yes | `{scaivault_path_pattern: backend_path_template}` |
| `mode` | Yes | `proxy` or `sync` |
| `sync_interval` | For `sync` | e.g. `15m` |

Example (HashiCorp):

```json
{
  "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):

```json
{
  "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:

```json
{
  "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](../advanced/federation)