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.
/api/v1/vaultAutomation 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.
/api/v1/vault/namespacesCreate 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
| Name | Type | Description |
|---|---|---|
name* | string | Display name (1–200 chars). Unique within the company. |
slug | string | URL-safe id (≤ 64 chars), unique within the company. Derived from name when omitted. |
description | string | Optional free-text description |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Namespace ID |
company_id* | string (UUID) | Owning organisation |
name* | string | Display name |
slug* | string | URL-safe id |
description* | string | null | Description, or null |
system_managed* | boolean | Whether another resource owns the namespace; false on create |
managed_by* | string | null | Owner kind (compute_api), or null |
managed_by_id* | string (UUID) | null | Owner ID (the compute API), or null |
created_by* | string (UUID) | null | Principal 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"
}/api/v1/vault/namespacesList 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
| Name | Type | Description |
|---|---|---|
managed | boolean | true lists only system-managed namespaces, false only ordinary ones; omit for both |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | 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"
}
]/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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Namespace ID |
company_id* | string (UUID) | Owning organisation |
name* | string | Display name |
slug* | string | URL-safe id |
description* | string | null | Description, or null |
system_managed* | boolean | Whether another resource (a compute API) owns the namespace |
managed_by* | string | null | Owner kind (compute_api), or null |
managed_by_id* | string (UUID) | null | Owner ID (the compute API), or null |
created_by* | string (UUID) | null | Creator 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"
}/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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | New display name (1–200 chars) |
description | string | New description |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Namespace ID |
company_id* | string (UUID) | Owning organisation |
name* | string | Display name |
slug* | string | URL-safe id |
description* | string | null | Description, or null |
system_managed* | boolean | Whether another resource (a compute API) owns the namespace |
managed_by* | string | null | Owner kind (compute_api), or null |
managed_by_id* | string (UUID) | null | Owner ID (the compute API), or null |
created_by* | string (UUID) | null | Creator 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"
}/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
| Name | Type | Description |
|---|---|---|
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 ContentCredentials
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.
/api/v1/vault/namespaces/{namespace_id}/credentialsCreate 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Parent namespace ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Display name (1–200 chars). Unique within the namespace. |
slug | string | Reference key (≤ 64 chars), unique within the namespace. Derived from name when omitted. |
type* | string | Credential 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 | string | How the material came to exist: supplied (you paste it) or generated (Vault generates it — Preview, returns 501).Default: supplied |
exportable | boolean | When 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 | object | Non-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* | string | The secret value (plaintext). Required for supplied credentials. Sealed immediately on write; never stored in the clear or returned. |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Credential ID |
company_id* | string (UUID) | Owning organisation |
namespace_id* | string (UUID) | Parent namespace |
name* | string | Display name |
slug* | string | Reference key |
type* | string | Credential type |
source* | string | supplied or generated |
exportable* | boolean | Whether the value can be resolved |
config* | object | Non-secret per-type config |
public_material* | string | null | Non-secret public half of a keypair (public key / certificate), or null. Never the secret. |
last_rotated_at* | string (ISO 8601) | null | When the material was last rotated, or null |
created_by* | string (UUID) | null | Creator 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"
}/api/v1/vault/namespaces/{namespace_id}/credentialsList 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Parent namespace ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | 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"
}
]/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
| Name | Type | Description |
|---|---|---|
credential_id* | string (UUID) | Credential ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Credential ID |
company_id* | string (UUID) | Owning organisation |
namespace_id* | string (UUID) | Parent namespace |
name* | string | Display name |
slug* | string | Reference key |
type* | string | Credential type |
source* | string | supplied or generated |
exportable* | boolean | Whether the value can be resolved |
config* | object | Non-secret per-type config |
public_material* | string | null | Public half for keypairs, or null. Never the secret. |
last_rotated_at* | string (ISO 8601) | null | When the material was last rotated, or null |
created_by* | string (UUID) | null | Creator 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"
}/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
| Name | Type | Description |
|---|---|---|
credential_id* | string (UUID) | Credential ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | New display name (1–200 chars) |
config | object | Replacement non-secret per-type config |
exportable | boolean | Toggle whether the value can be resolved |
material | string | New 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
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Credential ID |
namespace_id* | string (UUID) | Parent namespace |
name* | string | Display name |
type* | string | Credential type |
exportable* | boolean | Whether the value can be resolved |
config* | object | Non-secret per-type config |
public_material* | string | null | Public half for keypairs, or null |
last_rotated_at* | string (ISO 8601) | null | Updated 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"
}/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
| Name | Type | Description |
|---|---|---|
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 ContentOAuth 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.
/api/v1/vault/credentials/{credential_id}/oauth/completeComplete 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
| Name | Type | Description |
|---|---|---|
credential_id* | string (UUID) | The credential the connection was started for |
Request Body
| Name | Type | Description |
|---|---|---|
state* | string | state query parameter from the redirect (≤ 512 chars) |
code* | string | code query parameter from the redirect (≤ 4096 chars) |
Response Fields
| Name | Type | Description |
|---|---|---|
credential_id* | string (UUID) | Credential ID |
type* | string | Credential type |
status* | string | not_connected, connected, or reconnect_required (the provider rejected the refresh token; connect again) |
scope* | string | null | Scope the provider granted |
expires_at* | string (ISO 8601) | null | When the current access token expires |
refreshed_at* | string (ISO 8601) | null | Last token exchange |
connected_at* | string (ISO 8601) | null | When a user connected the account |
connected_by* | string (UUID) | null | User who connected the account |
last_error* | string | null | Last 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
}/api/v1/vault/credentials/{credential_id}/oauthGet 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
| Name | Type | Description |
|---|---|---|
credential_id* | string (UUID) | An OAuth credential |
Response Fields
| Name | Type | Description |
|---|---|---|
credential_id* | string (UUID) | Credential ID |
type* | string | Credential type |
status* | string | not_connected, connected, or reconnect_required (the provider rejected the refresh token; connect again) |
scope* | string | null | Scope the provider granted |
expires_at* | string (ISO 8601) | null | When the current access token expires |
refreshed_at* | string (ISO 8601) | null | Last token exchange |
connected_at* | string (ISO 8601) | null | When a user connected the account |
connected_by* | string (UUID) | null | User who connected the account |
last_error* | string | null | Last 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"
}/api/v1/vault/credentials/{credential_id}/oauthDisconnect 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
| Name | Type | Description |
|---|---|---|
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 ContentAccess 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.
/api/v1/vault/credentials/{credential_id}/accessesList 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
| Name | Type | Description |
|---|---|---|
credential_id* | string (UUID) | Credential ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Results to return (1–500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | 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"
}
]/api/v1/vault/activityList 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
| Name | Type | Description |
|---|---|---|
limit | integer | Results to return (1–500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | 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.
/api/v1/vault/namespaces/access/grants/batchCreate 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
| Name | Type | Description |
|---|---|---|
operations* | array | 1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | One result per expanded grant, ordered by operation, then resource, then permission |
summary* | object | Outcome 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}
}/api/v1/vault/namespaces/access/connect-credential-consumerConnect 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
| Name | Type | Description |
|---|---|---|
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 ContentHTTP/1.1 204 No Content/api/v1/vault/namespaces/{namespace_id}/access/grantsList 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (≥ 1)Default: 1 |
limit | integer | Page size (1–500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | GrantEntry[] | Grants on this namespace |
total* | integer | Total grants |
page* | integer | Page returned |
limit* | integer | Page 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
}/api/v1/vault/namespaces/{namespace_id}/access/grantsCreate 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | member, api_key, agent, role, team, automation, or workflow |
principal_id* | string | ID of the principal receiving the grant |
permission_id* | string | Permission to grant (must be grantable from a namespace) |
resource | string | Resource path to scope the grant to. Defaults to the namespace path; must be scoped under it (e.g. a specific credential). |
effect | string | allow or denyDefault: allow |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | New grant ID |
permission_id* | string | Permission granted |
name* | string | Permission name |
resource* | string | Scoped resource |
effect* | string | allow or deny |
is_system* | boolean | Whether 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"
}/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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
grant_id* | string | Grant 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/api/v1/vault/namespaces/{namespace_id}/access/connection-requestsList 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
status | string | Filter by status: pending, approved, rejectedDefault: pending |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | 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"
}
]/api/v1/vault/namespaces/{namespace_id}/access/connection-requests/{request_id}/approveApprove 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
request_id* | string | Connection request ID |
Request Body
| Name | Type | Description |
|---|---|---|
permissions | string[] | Override the permissions to grant. Defaults to the request's requested_permissions. Each must be grantable from a namespace. |
grant | boolean | Whether to issue the grant on approvalDefault: true |
label | string | Optional label for the resulting connection |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Request ID |
status* | string | approved |
connection_id | string | null | ID of the connection created on approval |
decided_by | string | null | Approver principal |
decided_at | string (ISO 8601) | null | When 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"
}/api/v1/vault/namespaces/{namespace_id}/access/connectionsList 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | 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"
}
]/api/v1/vault/namespaces/{namespace_id}/access/eligibleList 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
| Name | Type | Description |
|---|---|---|
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[]/api/v1/vault/namespaces/{namespace_id}/access/permissionsList 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
| Name | Type | Description |
|---|---|---|
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[]/api/v1/vault/namespaces/{namespace_id}/access/resource-typesGet 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
| Name | Type | Description |
|---|---|---|
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": [] }/api/v1/vault/namespaces/{namespace_id}/access/connection-requests/{request_id}/rejectReject 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
request_id* | string | Connection request ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional 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" }/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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID |
connection_id* | string | Connection 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 ContentCredential 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.
/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/eligibleList 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID (must own the credential) |
credential_id* | string (UUID) | Credential ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
permission | string | Only 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" }]/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/resource-typesGet 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
| Name | Type | Description |
|---|---|---|
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": [] }/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grantsList 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID (must own the credential) |
credential_id* | string (UUID) | Credential ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (≥ 1)Default: 1 |
limit | integer | Page 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 }/api/v1/vault/namespaces/{namespace_id}/credentials/{credential_id}/access/grantsCreate 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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID (must own the credential) |
credential_id* | string (UUID) | Credential ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | member, api_key, agent, role, team, automation, workflow, compute_api, or channel_config |
principal_id* | string | ID of the principal receiving the grant |
permission_id* | string (UUID) | Permission UUID from this credential's access/resource-types |
resource | string | When sent, must be exactly the credential path |
effect | string | allow 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"
}/api/v1/vault/credentials/access/grants/batchCreate 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
| Name | Type | Description |
|---|---|---|
operations* | array | 1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | One result per expanded grant, ordered by operation, then resource, then permission |
summary* | object | Outcome 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}
}/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
| Name | Type | Description |
|---|---|---|
namespace_id* | string (UUID) | Namespace ID (must own the credential) |
credential_id* | string (UUID) | Credential ID |
grant_id* | string | Grant 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}"