Vault

Key Concepts

Vault is built around two primitives that map directly onto the platform's unified access model: a namespace is a federated zone, and a credential is a governed leaf inside it.

Namespaces — the Federated Zone

A namespace is the top-level container — it belongs to an organization and is the unit you share with other principals. Creating a namespace mints the zone: it is registered in IAM's centralized resource tree so zone/leaf grant scoping applies, and the creator automatically receives the full sub-namespace bundle (which already covers creating credentials inside it). Granting use to anyone else is always a deliberate delegation from the namespace's access page, never automatic.

Credentials — the Governed Leaf

A credential is a single piece of typed secret material living inside a namespace. The secret is encrypted at rest the moment it is written (envelope encryption) and is stored only as ciphertext — there is no plaintext column anywhere. Each credential carries a type, a source, an exportable flag, a non-secret config (header name, token URL, username, …), and — for keypairs — a non-secret public_material half.

View vs. Use

Two permissions are deliberately independent. vault:credentials:view answers "does this credential exist, and what type is it?" — for authoring UIs, pickers, and audits; it never returns the secret. vault:credentials:use answers "may this principal use the value at runtime?" Resolution remains server-to-server and always audited. A namespace admin can curate credentials with manage + view without ever holding use; a machine principal can hold use on exactly one credential without view anywhere.

Credential Types & Sources

Every credential has a type (what kind of secret it holds) and a source (how the material came to exist). The config for each type holds only non-secret fields; the secret itself is always sealed in ciphertext.

Supplied

With source: supplied you paste the material and Vault seals it immediately. This is the only source supported today. Supplied types include:

• api_key — the key, with config: { placement, name } (header or query placement and the field name).
• bearer_token — the token, no extra config.
• basic_auth — the password, with config: { username }.
• oauth2_client_credentials — the client secret, with config: { client_id, token_url, scopes }.
• secret_value — an opaque secret string.
• config — a value that is non-secret but still access-gated.

curl -X POST https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/credentials \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe API Key",
    "type": "api_key",
    "source": "supplied",
    "exportable": true,
    "config": { "placement": "header", "name": "Authorization" },
    "material": "sk_live_51HxxxxxxxxxxxxYOURKEY"
  }'

Generated

With source: generated Vault would generate the material itself using the platform CSPRNG — random bytes, passwords, AES/HMAC keys, or keypairs (RSA, EC, Ed25519, SSH) — sealing the private/symmetric half and exposing the public half (if any) as public_material. Generated keypairs can be created non-exportable, so the private half never leaves Vault and can only be operated on.

Secret Resolution

Resolution is how a secret actually gets used. It happens server-side, over an internal channel, and is authorized against the acting principal — never against whoever happens to hold the service key. The calling principal that triggers the work need not ever see the secret.

How a Resolve Works

A trusted consuming service (for example, Compute) asks Vault to use a credential for an acting principal. The private service-to-service contract is intentionally omitted from this public guide. Vault then:

• Loads the credential by path (tenant-scoped — a mismatch is a 404, no existence oracle).
• Rejects the request if the credential is non-exportable (use is invalid for those — they can only be operated on).
• Asks IAM to check vault:credentials:use for the acting principal on that exact path.
• On allow: decrypts, writes a use / allow audit row, and returns { type, config, value }. On deny: returns 403 with no value and writes a deny audit row.

Credential Indirection

The recommended (but not required) pattern is use-without-seeing: a Compute collection holds vault:credentials:use, while an agent only holds permission to invoke that collection. The agent triggers the call, Compute resolves the secret as the collection principal, and the agent never sees the value and holds no vault:* grants at all. Any principal may be granted use directly when that is the intent — indirection is a modeling choice, not a wired-in rule.

A third permission completes the ladder: vault:credentials:operate lets a principal use a key without exporting it — sign, verify, encrypt, decrypt, or hmac performed entirely inside Vault. It is the only way to use a non-exportable key, and it is Preview / coming soon today.

Connections & Grants

Before a principal can resolve anything, it has to become eligible on the namespace. Vault uses the platform's standard connect-then-grant protocol, and it is principal- and service-agnostic: the consumer can be an agent, an automation, a workflow, a Compute collection, or any other principal.

Connect, then Grant

1. Connect. The consumer connects to the namespace — directly if it already holds vault:permissions:namespaces:manage, otherwise by raising a connection request that the namespace admin approves from the approver inbox.
2. Grant. The admin grants vault:credentials:use — scoped to a single credential (leaf) or the whole namespace.
3. Resolve. At runtime the consumer resolves via the internal endpoint; IAM enforces service access, the connection gate, and the grant.

# Approve a pending connection request and grant scoped use in one step.
curl -X POST "https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/connection-requests/{request_id}/approve" \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["vault:credentials:use"],
    "grant": true,
    "label": "Billing Sync"
  }'

# Or grant directly to a known principal, scoped to one credential.
curl -X POST https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "service",
    "principal_id": "{principal_id}",
    "permission_id": "{permission_id}",
    "resource": "org/{company_id}/namespace/{namespace_id}/credential/{credential_id}",
    "effect": "allow"
  }'

Common consumers include Compute collections that resolve a secret to call a third-party API, automations that rotate or apply credentials on a schedule, and agents that drive a collection without ever touching the value. A sensitive namespace can additionally set an allowed_consumer_services allow-list (Preview) to restrict which services may become eligible at all.