Vault

Store, govern, and resolve secrets — API keys, tokens, passwords, and keys — so the principals that use them never have to see them.

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.

No management endpoint ever returns a secret value. Create, read, list, and update all respond with metadata only. Trusted platform services can resolve values server-side for exportable credentials, but that internal contract is not part of the public API or agent tool catalog.

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 }. Vault exchanges the secret for access tokens and refreshes them; consumers receive only the access token.
  • oauth2_authorization_code — the client secret, with config: { client_id, authorize_url, token_url, scopes }. A user connects the account once from the credential in Vault (register {app origin}/oauth/callback as the OAuth app's redirect URI); Vault keeps the token refreshed and asks for a reconnect if the provider revokes it.
  • oauth2_jwt_bearer — a PEM private key (RSA, EC P-256/P-384 or Ed25519), with config: { token_url, issuer, subject?, audience?, scopes }. The RFC 7523 JWT Bearer grant: Vault signs a short-lived assertion with the key for every token request, so there is no client secret and no refresh token.
  • signed_jwt — a PEM private key (RSA, EC P-256/P-384 or Ed25519) or an HMAC secret, with config: { issuer, audience, subject?, kid?, algorithm?, secret_encoding?, lifetime_s?, iat_skew_s?, extra_claims? }. For APIs that take a JWT you sign as the bearer credential, with no token endpoint (App Store Connect, Snowflake key-pair auth): every resolve returns a new short-lived JWT signed with the key, and the key never leaves Vault. algorithm (HS256, HS384 or HS512) is only for an HMAC secret; a PEM key sets its own.
  • 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": "<stripe-secret-key>"
  }'

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.

Generated material is Preview / coming soon. Today, requests with source: generated return 501 — create credentials with source: supplied and provide the material. Server-side operate (the non-exportable-key path) is Preview as well. To replace material, PATCH the credential with new material.

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). OAuth and Signed JWT credentials are the exception: they resolve to a brokered access token or a freshly signed JWT, and the client secret or key never leaves Vault.
  • 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 API holds vault:credentials:use, while an agent only holds permission to invoke that API. The agent triggers the call, Compute resolves the secret as the API 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.

Every resolve attempt — allow or deny — is recorded. Read the trail per credential at GET /credentials/{id}/accesses or org-wide at GET /activity. Audit rows and event payloads carry references only — never the secret value.

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 API, 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 APIs that resolve a secret to call a third-party service, automations that rotate or apply credentials on a schedule, and agents that drive an API without ever touching the value. To keep a sensitive namespace tight, grant on a single credential instead of the whole namespace: each credential has its own Manage security dialog (under the namespace's Security tab), backed by /namespaces/{namespace_id}/credentials/{credential_id}/access/*, which only offers the permissions that credential's type supports.

This access model powers every service on the platform. For the full lifecycle — principals, grants, connection requests, and runtime enforcement — see the Permissions guide.

Ready to start building? Head to the Vault API Reference for the complete list of endpoints, request parameters, and response schemas.