API Integration

EDCS API Integration

EDCS exposes OAuth2-protected APIs for secrets (Vault), application configuration (AppConfig), and directory users/groups. This guide is for developers and AI agents. No credentials appear here — secrets are shown only as <placeholders>.

Full machine-readable spec Create an account Sign in

1. Get a token

All resource APIs require a JWT from the Identity STS token endpoint (POST {sts}/connect/token, form-encoded). Find the issuer and keys at {sts}/.well-known/openid-configuration.

Human users — password grant:

grant_type=password
username=<username>
password=<password>
scope=openid

Services & AI agents — client credentials:

grant_type=client_credentials
client_id=<client-id>
client_secret=<client-secret>
scope=vault:read appconfig:read

Send it on every request: Authorization: Bearer <access_token>. Granted scopes never exceed what your account's groups (or a client's allowed scopes) permit.

2. Scopes

Scope	Grants
`edcs:admin`	Everything (wildcard)
`vault:read`	Read secrets, versions, audit
`vault:write`	Write / delete / restore secrets
`appconfig:read`	Read config & feature flags
`appconfig:write`	Write / delete config
`directory:read`	Read users & groups
`directory:write`	Create users
`directory:admin`	Delete users, reset passwords, lock, manage groups

Insufficient scope → 403; missing/invalid token → 401.

3. Example — read a secret (curl)

TOKEN=$(curl -s -X POST "$STS/connect/token" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d scope=vault:read | jq -r .access_token)

curl -s "$VAULT/v1/secrets/myapp/db-password" \
  -H "Authorization: Bearer $TOKEN"

4. OpenAPI / Swagger

Each service publishes an interactive Swagger UI and a machine-readable schema:

{sts}/swagger — Identity STS
{vault}/swagger — Vault API
{appconfig}/swagger — AppConfig API
{directory}/swagger — Directory API

The JSON schema for any service is at {service}/swagger/v1/swagger.json.

MCP server (Claude / AI agents)

EDCS ships a Model Context Protocol server exposing read-only tools (vault, appconfig, directory) backed by a scoped edcs-mcp service identity. Run it locally over stdio with Claude Code/Desktop (see .mcp.json in the repo), or connect to the deployed Streamable HTTP endpoint at https://edcs-mcp.securitasmachina.org/mcp. The HTTP endpoint requires an API key (Authorization: Bearer <key>) and runs read-only without vault access — read secret values via local stdio only.

Tools: vault_read_secret, vault_list_paths, app_config_get_value, directory_list_users, and more. The server's scopes bound what the tools can reach.

For AI agents (Claude)

Use the client_credentials grant with the narrowest scope your task needs. Tokens are short-lived (~5–15 min) — request a fresh one rather than caching. Fetch /api-spec.md for the full endpoint reference, or any service's /swagger/v1/swagger.json for the OpenAPI schema. Never log or echo token values or secret contents.

Self-registered accounts are created locked and require administrator approval before sign-in.