Vault

Store, govern, and resolve secret material — API keys, tokens, passwords, and keys — without ever exposing the secret to the principal that uses it. A namespace is a federated zone; a credential is a governed leaf encrypted at rest. No public endpoint ever returns a secret value: secrets are decrypted only at the internal, server-to-server resolve endpoint, only for exportable credentials (OAuth credentials resolve to a brokered access token and Signed JWT credentials to a JWT Vault signs instead, so their secret never leaves Vault), and every resolve is authorized against the acting principal and audited.

Base URL/api/v1/vault

Automation triggers: view every Vault event, payload field, and predicate.

Namespaces

CRUD on namespaces — the federated zone that contains credentials. Creating a namespace mints the IAM zone and grants the creator the full sub-namespace bundle (which already covers creating credentials inside it). All public routes require a JWT and the X-Company-Id header.

POST/api/v1/vault/namespaces

Create Namespace

Create a namespace (mints the federated zone). The creator automatically receives vault:namespaces:* and vault:permissions:namespaces:manage on the new namespace path.

Bearer token required. Header: X-Company-Id. Permission: vault:namespaces:create (granted on org/{company_id}).

Request Body

NameTypeDescription
name*
stringDisplay name (1–200 chars). Unique within the company.
slug
stringURL-safe id (≤ 64 chars), unique within the company. Derived from name when omitted.
description
stringOptional free-text description

Response Fields

NameTypeDescription
id*
string (UUID)Namespace ID
company_id*
string (UUID)Owning organisation
name*
stringDisplay name
slug*
stringURL-safe id
description*
string | nullDescription, or null
system_managed*
booleanWhether another resource owns the namespace; false on create
managed_by*
string | nullOwner kind (compute_api), or null
managed_by_id*
string (UUID) | nullOwner ID (the compute API), or null
created_by*
string (UUID) | nullPrincipal that created the namespace, or null
created_at*
string (ISO 8601)Creation time
updated_at*
string (ISO 8601)Last update time
curl -X POST https://platform.ergondata.ai/api/v1/vault/namespaces \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integrations",
    "slug": "production-integrations",
    "description": "Third-party API credentials for production."
  }'

Response

201 Created
{
  "id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Production Integrations",
  "slug": "production-integrations",
  "description": "Third-party API credentials for production.",
  "system_managed": false,
  "managed_by": null,
  "managed_by_id": null,
  "created_by": "u9000000-0000-4000-8000-000000000001",
  "created_at": "2026-04-14T10:30:00Z",
  "updated_at": "2026-04-14T10:30:00Z"
}
GET/api/v1/vault/namespaces

List Namespaces

List namespaces for the company. Results are filtered to the namespaces the caller can view (vault:namespaces:view on the org or on a specific namespace path).

Bearer token required. Header: X-Company-Id. Filtered by vault:namespaces:view.

Query Parameters

NameTypeDescription
managed
booleantrue lists only system-managed namespaces, false only ordinary ones; omit for both

Response Fields

NameTypeDescription
[]*
Namespace[]Visible namespaces, newest first
curl https://platform.ergondata.ai/api/v1/vault/namespaces \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
[
  {
    "id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Production Integrations",
    "slug": "production-integrations",
    "description": "Third-party API credentials for production.",
    "system_managed": false,
    "managed_by": null,
    "managed_by_id": null,
    "created_by": "u9000000-0000-4000-8000-000000000001",
    "created_at": "2026-04-14T10:30:00Z",
    "updated_at": "2026-04-14T10:30:00Z"
  }
]
GET/api/v1/vault/namespaces/{namespace_id}

Get Namespace

Retrieve a single namespace by ID.

Bearer token required. Header: X-Company-Id. Permission: vault:namespaces:view (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID

Response Fields

NameTypeDescription
id*
string (UUID)Namespace ID
company_id*
string (UUID)Owning organisation
name*
stringDisplay name
slug*
stringURL-safe id
description*
string | nullDescription, or null
system_managed*
booleanWhether another resource (a compute API) owns the namespace
managed_by*
string | nullOwner kind (compute_api), or null
managed_by_id*
string (UUID) | nullOwner ID (the compute API), or null
created_by*
string (UUID) | nullCreator principal, or null
created_at*
string (ISO 8601)Creation time
updated_at*
string (ISO 8601)Last update time
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id} \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
{
  "id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Production Integrations",
  "slug": "production-integrations",
  "description": "Third-party API credentials for production.",
  "system_managed": false,
  "managed_by": null,
  "managed_by_id": null,
  "created_by": "u9000000-0000-4000-8000-000000000001",
  "created_at": "2026-04-14T10:30:00Z",
  "updated_at": "2026-04-14T10:30:00Z"
}
PATCH/api/v1/vault/namespaces/{namespace_id}

Update Namespace

Update a namespace's name or description. Only the supplied fields change. A system-managed namespace cannot be renamed (409, detail.code namespace_managed); its description can change.

Bearer token required. Header: X-Company-Id. Permission: vault:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID

Request Body

NameTypeDescription
name
stringNew display name (1–200 chars)
description
stringNew description

Response Fields

NameTypeDescription
id*
string (UUID)Namespace ID
company_id*
string (UUID)Owning organisation
name*
stringDisplay name
slug*
stringURL-safe id
description*
string | nullDescription, or null
system_managed*
booleanWhether another resource (a compute API) owns the namespace
managed_by*
string | nullOwner kind (compute_api), or null
managed_by_id*
string (UUID) | nullOwner ID (the compute API), or null
created_by*
string (UUID) | nullCreator principal, or null
created_at*
string (ISO 8601)Creation time
updated_at*
string (ISO 8601)Last update time
curl -X PATCH https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id} \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Production-only third-party credentials."
  }'

Response

200 OK
{
  "id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Production Integrations",
  "slug": "production-integrations",
  "description": "Production-only third-party credentials.",
  "system_managed": false,
  "managed_by": null,
  "managed_by_id": null,
  "created_by": "u9000000-0000-4000-8000-000000000001",
  "created_at": "2026-04-14T10:30:00Z",
  "updated_at": "2026-04-14T11:02:11Z"
}
DELETE/api/v1/vault/namespaces/{namespace_id}

Delete Namespace

Delete a namespace. Cascades to all credentials (and their versions) inside it, and soft-deletes the IAM resource. Only the compute API that owns a system-managed namespace can delete it; this route returns 409 (detail.code namespace_managed) for it.

Bearer token required. Header: X-Company-Id. Permission: vault:namespaces:delete (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
curl -X DELETE https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id} \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

204 No Content

Credentials

CRUD on credentials — the governed leaf — inside a namespace. A credential carries a type, a source (supplied or generated), an exportable flag, non-secret config, and (for keypairs) public_material. The secret material is encrypted at rest the moment it is written and lives only as ciphertext. No endpoint in this section ever returns a secret value — not on create, not on read. The value is decrypted only by trusted services through Vault's private internal contract, and only for exportable credentials (OAuth and Signed JWT credentials excepted: they resolve to a brokered access token or a freshly signed JWT). Today only source=supplied is accepted; generated material is Preview and returns 501.

POST/api/v1/vault/namespaces/{namespace_id}/credentials

Create Credential

Create a credential inside a namespace. The plaintext material is sealed (envelope-encrypted) immediately and never persisted, logged, or echoed — the response is metadata only. Set exportable=false to make a key that can never be resolved, only operated on (Preview). source=generated is Preview and returns 501; create with source=supplied and provide material. A system-managed namespace refuses new credentials (409, detail.code namespace_managed).

Bearer token required. Header: X-Company-Id. Permission: vault:namespaces:credentials:create (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Parent namespace ID

Request Body

NameTypeDescription
name*
stringDisplay name (1–200 chars). Unique within the namespace.
slug
stringReference key (≤ 64 chars), unique within the namespace. Derived from name when omitted.
type*
stringCredential type. Supplied types: api_key, bearer_token, basic_auth, oauth2_client_credentials, oauth2_authorization_code, oauth2_jwt_bearer, signed_jwt, secret_value, config. Generated types (Preview): random_bytes, password, aes_key, hmac_key, rsa_keypair, ec_keypair, ed25519_keypair, ssh_keypair. For oauth2_client_credentials and oauth2_authorization_code the material is the client secret; for oauth2_jwt_bearer it is an unencrypted PEM private key (RSA 2048+, EC P-256 or P-384, or Ed25519), checked on create. Vault uses it to obtain access tokens. For signed_jwt it is such a PEM private key or an HMAC secret (at least 32, 48 or 64 bytes for HS256, HS384 or HS512), checked against config.algorithm on create; Vault signs a new JWT with it on every resolve.
source
stringHow the material came to exist: supplied (you paste it) or generated (Vault generates it — Preview, returns 501).Default: supplied
exportable
booleanWhen true, the value can be resolved via vault:credentials:use. When false, the secret never leaves Vault and can only be operated on (Preview). Defaults to true, except oauth2_jwt_bearer and signed_jwt, which are always false (true returns 400 vault.errors.credentialNeverExportable); they still resolve to an access token or a signed JWT.Default: true
config
objectNon-secret per-type config, e.g. {placement, name, prefix} for api_key, {username} for basic_auth, {client_id, token_url, scopes, auth_method, audience} for oauth2_client_credentials, and {client_id, authorize_url, token_url, scopes, auth_method, audience, pkce, extra_authorize_params} for oauth2_authorization_code. OAuth URLs must be absolute https URLs. auth_method is client_secret_basic (default) or client_secret_post; pkce defaults to true. audience is optional: the client-credentials token request carries it, and for authorization code it goes on the authorize request. oauth2_jwt_bearer takes {token_url, issuer, subject, audience, scopes, kid, lifetime_s, iat_skew_s, extra_claims, exchange, account_url, account_fields} with token_url and issuer required and no client_id: Vault signs an RFC 7523 assertion with iss = issuer, sub = subject (when set), aud = audience (default token_url) and the extra_claims, sets iat (backdated by iat_skew_s, at most 300), exp (lifetime_s, default 300, max 3600) and jti itself, and sends scopes as the scope form parameter. Providers that read the scope from the assertion (Google) take it in extra_claims as {"scope": "..."}. extra_claims may not set iss, sub, aud, iat, exp, nbf or jti. For a token endpoint that is not RFC 7523 (a GitHub App), exchange is {assertion_placement: body | authorization_header, body_format: form | json, params, response: {access_token_field, expiry_field, expiry_format: seconds | rfc3339}}; with authorization_header the assertion is the bearer token, the body is params alone (at most 4 KB, without grant_type, assertion or scope), scopes must be empty and aud is sent only when audience is set. account_url and account_fields ({login, name, avatar_url} mapped to dotted response paths) name the one GET Vault may sign to read the account the credential acts for; they need authorization_header placement and an account_url on the token_url host. signed_jwt takes {issuer, audience, subject, kid, algorithm, secret_encoding, lifetime_s, iat_skew_s, extra_claims} with issuer and audience required and no other key: every resolve signs a JWT with iss = issuer, aud = audience, sub = subject (when set), the extra_claims (same reserved claims refused), iat (backdated by iat_skew_s), exp (lifetime_s, default 300, max 3600) and jti, with kid in the header. A PEM key sets its own algorithm, so algorithm is only for an HMAC secret (HS256, HS384 or HS512); secret_encoding (text, the default, hex or base64) says how that secret is written. For api_key, placement is header (default) or query, name is the header (a valid HTTP header name) or query parameter, and the optional prefix is one word such as Token or Bot, sent before the key and a space, for header placement only; an invalid name or prefix is a 400. Never holds the secret.Default: {}
material*
stringThe secret value (plaintext). Required for supplied credentials. Sealed immediately on write; never stored in the clear or returned.

Response Fields

NameTypeDescription
id*
string (UUID)Credential ID
company_id*
string (UUID)Owning organisation
namespace_id*
string (UUID)Parent namespace
name*
stringDisplay name
slug*
stringReference key
type*
stringCredential type
source*
stringsupplied or generated
exportable*
booleanWhether the value can be resolved
config*
objectNon-secret per-type config
public_material*
string | nullNon-secret public half of a keypair (public key / certificate), or null. Never the secret.
last_rotated_at*
string (ISO 8601) | nullWhen the material was last rotated, or null
created_by*
string (UUID) | nullCreator principal, or null
created_at*
string (ISO 8601)Creation time
updated_at*
string (ISO 8601)Last update time
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>"
  }'

Response

201 Created
{
  "id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "namespace_id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
  "name": "Stripe API Key",
  "slug": "stripe-api-key",
  "type": "api_key",
  "source": "supplied",
  "exportable": true,
  "config": { "placement": "header", "name": "Authorization" },
  "public_material": null,
  "last_rotated_at": null,
  "created_by": "u9000000-0000-4000-8000-000000000001",
  "created_at": "2026-04-14T10:35:00Z",
  "updated_at": "2026-04-14T10:35:00Z"
}
GET/api/v1/vault/namespaces/{namespace_id}/credentials

List Credentials

List credentials in a namespace (metadata only). Results are filtered to the credentials the caller can view. The secret value is never included.

Bearer token required. Header: X-Company-Id. Filtered by vault:credentials:view.

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Parent namespace ID

Response Fields

NameTypeDescription
[]*
Credential[]Visible credentials (metadata only), newest first
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/credentials \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
[
  {
    "id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "namespace_id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
    "name": "Stripe API Key",
    "slug": "stripe-api-key",
    "type": "api_key",
    "source": "supplied",
    "exportable": true,
    "config": { "placement": "header", "name": "Authorization" },
    "public_material": null,
    "last_rotated_at": null,
    "created_by": "u9000000-0000-4000-8000-000000000001",
    "created_at": "2026-04-14T10:35:00Z",
    "updated_at": "2026-04-14T10:35:00Z"
  }
]
GET/api/v1/vault/credentials/{credential_id}

Get Credential

Retrieve a credential's metadata — type, config, and public_material (for keypairs). This endpoint never returns the secret value.

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:view (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)Credential ID

Response Fields

NameTypeDescription
id*
string (UUID)Credential ID
company_id*
string (UUID)Owning organisation
namespace_id*
string (UUID)Parent namespace
name*
stringDisplay name
slug*
stringReference key
type*
stringCredential type
source*
stringsupplied or generated
exportable*
booleanWhether the value can be resolved
config*
objectNon-secret per-type config
public_material*
string | nullPublic half for keypairs, or null. Never the secret.
last_rotated_at*
string (ISO 8601) | nullWhen the material was last rotated, or null
created_by*
string (UUID) | nullCreator principal, or null
created_at*
string (ISO 8601)Creation time
updated_at*
string (ISO 8601)Last update time
curl https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id} \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
{
  "id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "namespace_id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
  "name": "Stripe API Key",
  "slug": "stripe-api-key",
  "type": "api_key",
  "source": "supplied",
  "exportable": true,
  "config": { "placement": "header", "name": "Authorization" },
  "public_material": null,
  "last_rotated_at": null,
  "created_by": "u9000000-0000-4000-8000-000000000001",
  "created_at": "2026-04-14T10:35:00Z",
  "updated_at": "2026-04-14T10:35:00Z"
}
PATCH/api/v1/vault/credentials/{credential_id}

Update Credential

Update a credential's metadata or replace its secret material. Supplying material re-seals the value (envelope-encrypted) and stamps last_rotated_at; the plaintext is never persisted or returned. Setting exportable to false seals the credential, then revokes the use and vault:credentials:* grants on its path; if that revoke fails the credential stays sealed, the update returns 502, and repeating it finishes the revoke. OAuth and Signed JWT credentials are never sealed: exportable does not gate them and their grants are kept. The response is metadata only. For OAuth credentials, changing client_id, token_url, authorize_url, scopes or audience forgets stored tokens (rotating only the secret keeps them), and changing token_url requires material in the same request (400 vault.errors.oauthTokenUrlRequiresSecret). For oauth2_jwt_bearer, changing token_url, issuer, subject, audience, scopes, extra_claims or exchange forgets stored tokens (rotating the private key, changing account_url or account_fields, or editing kid, lifetime_s or iat_skew_s keeps them), and changing any of those but scopes, or account_url or account_fields, requires the private key as material in the same request (400 vault.errors.oauthAssertionRequiresKey). For signed_jwt, changing issuer, subject, audience, extra_claims, algorithm or secret_encoding requires the key as material in the same request (400 vault.errors.signedJwtClaimsRequireKey); kid, lifetime_s and iat_skew_s change without it. In a system-managed namespace only the material and config.scopes may change; changing name, exportable or any other config key returns 409 (detail.code namespace_managed).

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:manage (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)Credential ID

Request Body

NameTypeDescription
name
stringNew display name (1–200 chars)
config
objectReplacement non-secret per-type config
exportable
booleanToggle whether the value can be resolved
material
stringNew secret value (plaintext). When provided, the credential is re-sealed and last_rotated_at is updated. Never stored in the clear or returned.

Response Fields

NameTypeDescription
id*
string (UUID)Credential ID
namespace_id*
string (UUID)Parent namespace
name*
stringDisplay name
type*
stringCredential type
exportable*
booleanWhether the value can be resolved
config*
objectNon-secret per-type config
public_material*
string | nullPublic half for keypairs, or null
last_rotated_at*
string (ISO 8601) | nullUpdated when material is replaced
updated_at*
string (ISO 8601)Last update time
curl -X PATCH https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id} \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "material": "<rotated-stripe-secret-key>"
  }'

Response

200 OK
{
  "id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "namespace_id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
  "name": "Stripe API Key",
  "slug": "stripe-api-key",
  "type": "api_key",
  "source": "supplied",
  "exportable": true,
  "config": { "placement": "header", "name": "Authorization" },
  "public_material": null,
  "last_rotated_at": "2026-04-14T12:00:00Z",
  "created_by": "u9000000-0000-4000-8000-000000000001",
  "created_at": "2026-04-14T10:35:00Z",
  "updated_at": "2026-04-14T12:00:00Z"
}
DELETE/api/v1/vault/credentials/{credential_id}

Delete Credential

Delete a credential and its sealed material, and soft-delete the IAM resource. Credentials in a system-managed namespace cannot be deleted (409, detail.code namespace_managed).

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:delete (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)Credential ID
curl -X DELETE https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id} \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

204 No Content

OAuth Connections

Vault is the OAuth token broker for oauth2_client_credentials, oauth2_authorization_code and oauth2_jwt_bearer credentials: it exchanges the client secret (or, for JWT Bearer, an assertion it signs with the private key) with the provider's token endpoint, stores the tokens encrypted, renews them shortly before they expire, and hands only the access token to the internal resolve endpoint. The client secret, refresh token and private key never leave Vault. Client-credentials and JWT Bearer credentials get a token on first use; JWT Bearer has no refresh token, so Vault signs a new assertion when the token expires, and a rejected assertion is an exchange failure, not a reconnect. Authorization-code credentials are connected once by a signed-in user through a browser redirect: start with authorize, send the user to the returned URL, and finish with complete when the provider redirects back to {origin}/oauth/callback. Register that redirect URI with the OAuth app. No endpoint in this section returns a token.

POST/api/v1/vault/credentials/{credential_id}/oauth/authorize

Start OAuth Connection

Start connecting an oauth2_authorization_code credential for the signed-in user. Vault records a single-use state bound to that user and a PKCE verifier, and returns the provider authorization URL to send the browser to. The state expires after 10 minutes. Users only — API keys and agents get 403.

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:manage (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)An oauth2_authorization_code credential

Request Body

NameTypeDescription
origin*
stringOrigin of the app the user is in, e.g. https://platform.ergondata.ai. Must be an allowed app origin; the redirect URI is {origin}/oauth/callback.

Response Fields

NameTypeDescription
authorization_url*
stringProvider consent URL carrying client_id, redirect_uri, scope, state and the PKCE challenge
redirect_uri*
stringWhere the provider sends the user back
expires_at*
string (ISO 8601)When the state stops being accepted
curl -X POST https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id}/oauth/authorize \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{ "origin": "https://platform.ergondata.ai" }'

Response

200 OK
{
  "authorization_url": "https://accounts.example.com/o/oauth2/auth?response_type=code&client_id=ergon-app&redirect_uri=https%3A%2F%2Fplatform.ergondata.ai%2Foauth%2Fcallback&state=3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f.q1w2e3&scope=calendar.read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256",
  "redirect_uri": "https://platform.ergondata.ai/oauth/callback",
  "expires_at": "2026-04-14T10:45:00Z"
}
POST/api/v1/vault/credentials/{credential_id}/oauth/complete

Complete OAuth Connection

Finish the connection with the state and code the provider sent to the redirect URI. Only the user who started the connection can complete it, once, before the state expires. Vault exchanges the code (with the PKCE verifier) at the token endpoint and stores the tokens encrypted. Returns the connection status — never a token. Emits vault.credential.connected.

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:manage (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)The credential the connection was started for

Request Body

NameTypeDescription
state*
stringstate query parameter from the redirect (≤ 512 chars)
code*
stringcode query parameter from the redirect (≤ 4096 chars)

Response Fields

NameTypeDescription
credential_id*
string (UUID)Credential ID
type*
stringCredential type
status*
stringnot_connected, connected, or reconnect_required (the provider rejected the refresh token; connect again)
scope*
string | nullScope the provider granted
expires_at*
string (ISO 8601) | nullWhen the current access token expires
refreshed_at*
string (ISO 8601) | nullLast token exchange
connected_at*
string (ISO 8601) | nullWhen a user connected the account
connected_by*
string (UUID) | nullUser who connected the account
last_error*
string | nullLast failure, with the provider's OAuth error code (never its error_description)
curl -X POST https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id}/oauth/complete \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{ "state": "{state}", "code": "{code}" }'

Response

200 OK
{
  "credential_id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
  "type": "oauth2_authorization_code",
  "status": "connected",
  "scope": "calendar.read",
  "expires_at": "2026-04-14T11:35:00Z",
  "refreshed_at": "2026-04-14T10:35:00Z",
  "connected_at": "2026-04-14T10:35:00Z",
  "connected_by": "u9000000-0000-4000-8000-000000000001",
  "last_error": null
}
GET/api/v1/vault/credentials/{credential_id}/oauth

Get OAuth Connection

Whether an OAuth credential is connected, the granted scope and when its access token expires. A client-credentials credential reads not_connected until its first resolve. Never returns a token.

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:view (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)An OAuth credential

Response Fields

NameTypeDescription
credential_id*
string (UUID)Credential ID
type*
stringCredential type
status*
stringnot_connected, connected, or reconnect_required (the provider rejected the refresh token; connect again)
scope*
string | nullScope the provider granted
expires_at*
string (ISO 8601) | nullWhen the current access token expires
refreshed_at*
string (ISO 8601) | nullLast token exchange
connected_at*
string (ISO 8601) | nullWhen a user connected the account
connected_by*
string (UUID) | nullUser who connected the account
last_error*
string | nullLast failure, with the provider's OAuth error code (never its error_description)
curl https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id}/oauth \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
{
  "credential_id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
  "type": "oauth2_authorization_code",
  "status": "reconnect_required",
  "scope": "calendar.read",
  "expires_at": null,
  "refreshed_at": "2026-04-14T10:35:00Z",
  "connected_at": "2026-04-14T10:35:00Z",
  "connected_by": "u9000000-0000-4000-8000-000000000001",
  "last_error": "invalid_grant"
}
DELETE/api/v1/vault/credentials/{credential_id}/oauth

Disconnect OAuth Credential

Delete the tokens Vault holds for the credential and any pending connection. An authorization-code credential must be connected again before it resolves; a client-credentials or JWT Bearer credential exchanges a new token on its next resolve. Vault does not revoke the token at the provider. Emits vault.credential.disconnected when tokens were stored. Changing client_id, token_url, authorize_url, scopes or audience disconnects it the same way (for JWT Bearer: token_url, issuer, subject, audience, scopes, extra_claims or exchange); rotating the client secret or private key, or editing other config such as kid, lifetime_s, iat_skew_s or the account lookup, keeps the tokens.

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:manage (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)An OAuth credential
curl -X DELETE https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id}/oauth \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

204 No Content

Access Audit

Read the audit trail. Every resolve attempt — allow or deny — writes a credential_accesses row, and every namespace/credential mutation writes an activity log. Neither ever exposes a secret value.

GET/api/v1/vault/credentials/{credential_id}/accesses

List Credential Accesses

Who resolved this credential, when, and with what outcome (allow or deny). One row per resolve attempt; the value is never stored or returned.

Bearer token required. Header: X-Company-Id. Permission: vault:credentials:view (on the credential or its namespace).

Path Parameters

NameTypeDescription
credential_id*
string (UUID)Credential ID

Query Parameters

NameTypeDescription
limit
integerResults to return (1–500)Default: 100

Response Fields

NameTypeDescription
[]*
AccessEntry[]Access attempts, newest first
curl "https://platform.ergondata.ai/api/v1/vault/credentials/{credential_id}/accesses?limit=50" \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
[
  {
    "id": "ac1d0001-0000-4000-8000-000000000001",
    "credential_id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
    "acting_principal_id": "cc110000-0000-4000-8000-000000000009",
    "acting_principal_type": "service",
    "via_service": "compute",
    "action": "use",
    "outcome": "allow",
    "deny_reason": null,
    "accessed_at": "2026-04-14T11:20:05Z"
  },
  {
    "id": "ac1d0002-0000-4000-8000-000000000002",
    "credential_id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
    "acting_principal_id": "a9ent000-0000-4000-8000-000000000003",
    "acting_principal_type": "agent",
    "via_service": "compute",
    "action": "use",
    "outcome": "deny",
    "deny_reason": "use_denied",
    "accessed_at": "2026-04-14T11:18:42Z"
  }
]
GET/api/v1/vault/activity

List Activity

Org-scoped namespace/credential mutation log (created/updated/deleted, resolves). Diffs carry type, non-secret config, and metadata only — never secret material.

Bearer token required. Header: X-Company-Id. Permission: vault:activity:view (granted on org/{company_id}).

Query Parameters

NameTypeDescription
limit
integerResults to return (1–500)Default: 100

Response Fields

NameTypeDescription
[]*
ActivityEntry[]Activity log entries, newest first
curl "https://platform.ergondata.ai/api/v1/vault/activity?limit=50" \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
[
  {
    "id": "10900001-0000-4000-8000-000000000001",
    "event_type": "vault.credential.created",
    "actor_id": "u9000000-0000-4000-8000-000000000001",
    "actor_type": "member",
    "namespace_id": "9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
    "credential_id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
    "payload": {
      "credential_id": "3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
      "type": "api_key",
      "source": "supplied",
      "exportable": true,
      "config": { "placement": "header", "name": "Authorization" }
    },
    "created_at": "2026-04-14T10:35:00Z"
  }
]

Access & Connections

Each namespace exposes the platform's standard per-zone access + connection surface under /namespaces/{namespace_id}/access/*. It is the same connect-then-grant protocol used across the platform: view/create/revoke IAM grants, run the approver inbox for consumer connection requests, and list active inbound connections. Every endpoint here is gated by vault:permissions:namespaces:manage on the namespace, and all grant/connection logic is delegated to IAM — Vault stores no grants of its own.

POST/api/v1/vault/namespaces/access/grants/batch

Create Namespace Access Grants Batch

Create grants across namespace roots in one ordered, partial-success operation. Group a subject with resources and permission UUIDs; operations expand resources first and permission IDs second, to at most 200 grants total. Invalid or unauthorized items fail independently while valid items continue, and partial success returns 200. Whole-request retries are idempotent because existing natural grant tuples return already_exists. A side_effect_error means post-write reconciliation failed but the returned grant exists; retry that item or the whole request to reconcile it. ToolDef slug: vault.namespace_access.create_grants_batch.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage on every target namespace root.

Request Body

NameTypeDescription
operations*
array1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants

Response Fields

NameTypeDescription
results*
arrayOne result per expanded grant, ordered by operation, then resource, then permission
summary*
objectOutcome counts
curl -X POST https://platform.ergondata.ai/api/v1/vault/namespaces/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"client_ref":"consumers","principal_type":"workflow","principal_id":"{principal_id}","resources":["org/{company_id}/namespace/{namespace_id}/credential/{credential_id}"],"permission_ids":["{permission_id}"],"effect":"allow"}]}'

Response

200 OK
{
  "results": [{
    "index": 0,
    "client_ref": "consumers",
    "status": "created",
    "principal_type": "workflow",
    "principal_id": "{principal_id}",
    "permission_id": "{permission_id}",
    "resource": "org/{company_id}/namespace/{namespace_id}/credential/{credential_id}",
    "effect": "allow",
    "grant": {"id": "{grant_id}", "permission_id": "{permission_id}", "name": "vault:credentials:use", "resource": "org/{company_id}/namespace/{namespace_id}/credential/{credential_id}", "effect": "allow", "is_system": false, "granted_at": "2026-07-15T16:30:00Z"},
    "error_status": null,
    "error_detail": null,
    "side_effect_error_status": null,
    "side_effect_error_detail": null
  }],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}
POST/api/v1/vault/namespaces/access/connect-credential-consumer

Connect Credential Consumer

Connect a credential-consuming service principal (a Compute API or channel config) and grant it access to exactly the given credentials in one call. Each resource path must identify an existing credential in the active tenant. Vault approves a connect-only connection to each referenced namespace, then grants the requested permissions on exactly those credential paths, never on the namespace. Each credential gets only the requested permissions its type allows, so a non-exportable credential gets view without failing the others (a non-exportable OAuth or Signed JWT credential still gets use); a credential left with nothing grantable returns 400 before anything is written. Re-running it is idempotent.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage on every referenced namespace.

Request Body

NameTypeDescription
principal_type*
"compute_api" | "channel_config"Type of the credential-consuming principal
principal_id*
string (UUID)IAM principal UUID of the consumer
resources*
string[]1-20 credential resource paths of the form org/{company_id}/namespace/{namespace_id}/credential/{credential_id}
permissions
("vault:credentials:use" | "vault:credentials:view")[]Permissions granted on each credential pathDefault: ["vault:credentials:use", "vault:credentials:view"]
curl -X POST https://platform.ergondata.ai/api/v1/vault/namespaces/access/connect-credential-consumer \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{"principal_type":"channel_config","principal_id":"{principal_id}","resources":["org/{company_id}/namespace/{namespace_id}/credential/{credential_id}"]}'

Response

204 No Content
HTTP/1.1 204 No Content
GET/api/v1/vault/namespaces/{namespace_id}/access/grants

List Grants

List the IAM grants scoped to this namespace (and its credentials), paginated.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID

Query Parameters

NameTypeDescription
page
integerPage number (≥ 1)Default: 1
limit
integerPage size (1–500)Default: 100

Response Fields

NameTypeDescription
items*
GrantEntry[]Grants on this namespace
total*
integerTotal grants
page*
integerPage returned
limit*
integerPage size used
curl "https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/grants?limit=50" \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
{
  "items": [
    {
      "id": "9ra0t000-0000-4000-8000-000000000001",
      "principal_type": "service",
      "principal_id": "cc110000-0000-4000-8000-000000000009",
      "principal_label": "Billing Sync API",
      "permission_id": "perm_vault_credentials_use",
      "permission_name": "vault:credentials:use",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/namespace/9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90/credential/3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
      "effect": "allow",
      "granted_at": "2026-04-14T11:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}
POST/api/v1/vault/namespaces/{namespace_id}/access/grants

Create Grant

Grant a permission to a principal, scoped to this namespace or one of its credentials. Only namespace-grantable Vault permissions are accepted (e.g. vault:credentials:use, vault:credentials:view); the resource must be scoped under the namespace.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID

Request Body

NameTypeDescription
principal_type*
stringmember, api_key, agent, role, team, automation, or workflow
principal_id*
stringID of the principal receiving the grant
permission_id*
stringPermission to grant (must be grantable from a namespace)
resource
stringResource path to scope the grant to. Defaults to the namespace path; must be scoped under it (e.g. a specific credential).
effect
stringallow or denyDefault: allow

Response Fields

NameTypeDescription
id*
stringNew grant ID
permission_id*
stringPermission granted
name*
stringPermission name
resource*
stringScoped resource
effect*
stringallow or deny
is_system*
booleanWhether this is a system grant
granted_at*
string (ISO 8601)When the grant was created
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"
  }'

Response

201 Created
{
  "id": "9ra0t000-0000-4000-8000-000000000001",
  "permission_id": "perm_vault_credentials_use",
  "name": "vault:credentials:use",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/namespace/9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90/credential/3a7d9e10-2b4c-4d6e-9f01-2a3b4c5d6e7f",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-04-14T11:00:00Z"
}
DELETE/api/v1/vault/namespaces/{namespace_id}/access/grants/{grant_id}

Revoke Grant

Revoke a previously created grant on this namespace.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
grant_id*
stringGrant ID to revoke
curl -X DELETE https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

204 No Content
GET/api/v1/vault/namespaces/{namespace_id}/access/connection-requests

List Connection Requests

The approver inbox: connection requests raised by consumers that want to use this namespace. Filter by status (defaults to pending).

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID

Query Parameters

NameTypeDescription
status
stringFilter by status: pending, approved, rejectedDefault: pending

Response Fields

NameTypeDescription
[]*
ConnectionRequestEntry[]Connection requests targeting this namespace
curl "https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
[
  {
    "id": "c0nr0001-0000-4000-8000-000000000001",
    "principal_id": "cc110000-0000-4000-8000-000000000009",
    "principal_label": "Billing Sync API",
    "direction": "inbound",
    "target_service": "vault",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/namespace/9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
    "requested_by": "u9000000-0000-4000-8000-000000000002",
    "requested_permissions": ["vault:credentials:use"],
    "message": "Need to read the Stripe key for the billing sync.",
    "status": "pending",
    "connection_id": null,
    "decided_by": null,
    "decided_at": null,
    "created_at": "2026-04-14T10:55:00Z"
  }
]
POST/api/v1/vault/namespaces/{namespace_id}/access/connection-requests/{request_id}/approve

Approve Connection Request

Approve a consumer's connection request. Optionally narrow the granted permissions (each must be grantable from a namespace) and set a connection label. This connects the principal and, when grant is true, issues the requested use grant.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
request_id*
stringConnection request ID

Request Body

NameTypeDescription
permissions
string[]Override the permissions to grant. Defaults to the request's requested_permissions. Each must be grantable from a namespace.
grant
booleanWhether to issue the grant on approvalDefault: true
label
stringOptional label for the resulting connection

Response Fields

NameTypeDescription
id*
stringRequest ID
status*
stringapproved
connection_id
string | nullID of the connection created on approval
decided_by
string | nullApprover principal
decided_at
string (ISO 8601) | nullWhen it was approved
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"
  }'

Response

200 OK
{
  "id": "c0nr0001-0000-4000-8000-000000000001",
  "principal_id": "cc110000-0000-4000-8000-000000000009",
  "principal_label": "Billing Sync API",
  "direction": "inbound",
  "target_service": "vault",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/namespace/9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
  "requested_permissions": ["vault:credentials:use"],
  "message": "Need to read the Stripe key for the billing sync.",
  "status": "approved",
  "connection_id": "c0nn0001-0000-4000-8000-000000000007",
  "decided_by": "u9000000-0000-4000-8000-000000000001",
  "decided_at": "2026-04-14T11:00:00Z",
  "created_at": "2026-04-14T10:55:00Z"
}
GET/api/v1/vault/namespaces/{namespace_id}/access/connections

List Connections

List the active inbound connections to this namespace — the principals that have been connected and granted access.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID

Response Fields

NameTypeDescription
[]*
InboundConnectionEntry[]Active inbound connections to this namespace
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/connections \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK
[
  {
    "connection_id": "c0nn0001-0000-4000-8000-000000000007",
    "principal_id": "cc110000-0000-4000-8000-000000000009",
    "principal_label": "Billing Sync API",
    "target_service": "vault",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/namespace/9b1f8c2e-4d3a-4f1b-8a7c-2e5d6f7a8b90",
    "status": "active",
    "created_at": "2026-04-14T11:00:00Z"
  }
]
GET/api/v1/vault/namespaces/{namespace_id}/access/eligible

List Eligible Principals

List principals that are eligible to receive grants in this namespace after applying the connection gate.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/eligible \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

200 OK
[]
GET/api/v1/vault/namespaces/{namespace_id}/access/permissions

List Namespace Permissions

List Vault permissions that can be granted from the namespace access surface. Use the returned UUID as permission_id when creating a grant.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/permissions \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

200 OK
[]
GET/api/v1/vault/namespaces/{namespace_id}/access/resource-types

Get Namespace Resource Types

Return the namespace-to-credential resource-type chain plus the grantable permissions used by generic access clients.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/resource-types \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

200 OK
{ "chain": [], "permissions": [] }
POST/api/v1/vault/namespaces/{namespace_id}/access/connection-requests/{request_id}/reject

Reject Connection Request

Reject a pending inbound connection request for this namespace.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
request_id*
stringConnection request ID

Request Body

NameTypeDescription
reason
string | nullOptional rejection reason
curl -X POST https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" -d '{"reason":"Not approved"}'

Response

200 OK
{ "id": "{request_id}", "status": "rejected" }
DELETE/api/v1/vault/namespaces/{namespace_id}/access/connections/{connection_id}

Revoke Connection

Revoke an active inbound namespace connection and its associated access relationship.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the namespace path).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID
connection_id*
stringConnection ID
curl -X DELETE https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

204 No Content

Credential Access

A credential is a grant anchor inside its namespace, not a zone: it has its own grants surface under /namespaces/{namespace_id}/credentials/{credential_id}/access/* but no connections — consumers still connect to the namespace. Every endpoint is gated by vault:permissions:namespaces:manage resolved against the credential path, so namespace managers cascade. Grants target exactly the credential path. Only vault:credentials:* / view / use / operate / manage / delete are grantable, and only when the credential's type supports them: use needs an exportable credential (except on OAuth and signed_jwt types), operate needs a key type, and the vault:credentials:* wildcard needs both. Setting exportable to false revokes the use and wildcard grants on the credential's path; turning export back on does not restore them. OAuth and Signed JWT credentials are never sealed, so they keep their grants. Another tenant's credential returns 404.

GET/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/eligible

List Credential Eligible Principals

List principals eligible to receive a grant on this credential, optionally filtered by the permission to grant. ToolDef slug: vault.credential_access.list_eligible.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the credential path; a namespace grant covers it).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID (must own the credential)
credential_id*
string (UUID)Credential ID

Query Parameters

NameTypeDescription
permission
stringOnly principals eligible for this permission name
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/eligible \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

200 OK
[{ "principal_type": "compute_api", "principal_id": "{principal_id}", "label": "Billing Sync API" }]
GET/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/resource-types

Get Credential Resource Types

Return the resource-type chain plus the permissions grantable on this credential, already narrowed to what its type supports. Use permissions[].id as permission_id. ToolDef slug: vault.credential_access.list_resource_types.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the credential path; a namespace grant covers it).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID (must own the credential)
credential_id*
string (UUID)Credential ID
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/resource-types \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

200 OK
{ "resource_types": [], "permissions": [] }
GET/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grants

List Credential Grants

List the IAM grants minted on exactly this credential's path, paginated. Namespace, organization and global grants that also cover it are listed and revoked from the namespace. ToolDef slug: vault.credential_access.list_grants.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the credential path; a namespace grant covers it).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID (must own the credential)
credential_id*
string (UUID)Credential ID

Query Parameters

NameTypeDescription
page
integerPage number (≥ 1)Default: 1
limit
integerPage size (1–500)Default: 100
curl https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grants \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

200 OK
{ "items": [], "total": 0, "page": 1, "limit": 100 }
POST/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grants

Create Credential Grant

Grant a permission on exactly this credential. The permission must be credential-grantable and supported by the credential's type, otherwise 400. ToolDef slug: vault.credential_access.create_grant.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the credential path; a namespace grant covers it).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID (must own the credential)
credential_id*
string (UUID)Credential ID

Request Body

NameTypeDescription
principal_type*
stringmember, api_key, agent, role, team, automation, workflow, compute_api, or channel_config
principal_id*
stringID of the principal receiving the grant
permission_id*
string (UUID)Permission UUID from this credential's access/resource-types
resource
stringWhen sent, must be exactly the credential path
effect
stringallow or denyDefault: allow
curl -X POST https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grants \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{"principal_type":"compute_api","principal_id":"{principal_id}","permission_id":"{permission_id}"}'

Response

201 Created
{
  "id": "{grant_id}",
  "permission_id": "{permission_id}",
  "name": "vault:credentials:use",
  "resource": "org/{company_id}/namespace/{namespace_id}/credential/{credential_id}",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-04-14T11:00:00Z"
}
POST/api/v1/vault/credentials/access/grants/batch

Create Credential Access Grants Batch

Create grants across exact credential paths in one ordered, partial-success operation, with the same request and response contract as the namespace batch. Each resource must be an existing credential's exact path; each permission must be credential-grantable and supported by that credential's type. ToolDef slug: vault.credential_access.create_grants_batch.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage on every target credential path (a namespace grant covers it).

Request Body

NameTypeDescription
operations*
array1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants

Response Fields

NameTypeDescription
results*
arrayOne result per expanded grant, ordered by operation, then resource, then permission
summary*
objectOutcome counts
curl -X POST https://platform.ergondata.ai/api/v1/vault/credentials/access/grants/batch \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"client_ref":"runtime","principal_type":"compute_api","principal_id":"{principal_id}","resources":["org/{company_id}/namespace/{namespace_id}/credential/{credential_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK
{
  "results": [{
    "index": 0,
    "client_ref": "runtime",
    "status": "created",
    "principal_type": "compute_api",
    "principal_id": "{principal_id}",
    "permission_id": "{permission_id}",
    "resource": "org/{company_id}/namespace/{namespace_id}/credential/{credential_id}",
    "effect": "allow",
    "grant": {"id": "{grant_id}"},
    "error_status": null,
    "error_detail": null,
    "side_effect_error_status": null,
    "side_effect_error_detail": null
  }],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}
DELETE/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grants/{grant_id}

Revoke Credential Grant

Revoke a grant on this credential. Returns 404 for a grant on any other path, including the namespace that contains the credential. ToolDef slug: vault.credential_access.delete_grant.

Bearer token required. Header: X-Company-Id. Permission: vault:permissions:namespaces:manage (on the credential path; a namespace grant covers it).

Path Parameters

NameTypeDescription
namespace_id*
string (UUID)Namespace ID (must own the credential)
credential_id*
string (UUID)Credential ID
grant_id*
stringGrant ID to revoke
curl -X DELETE https://platform.ergondata.ai/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}" -H "X-Company-Id: {company_id}"

Response

204 No Content