2026-10-22
Vault stores write-only credentials through /vault/v1, with a compatibility face at /anthropic/v1/vaults. Concepts and behavior follow Anthropic vaults (credential collections, write-only values, rotation and archival), so Anthropic experience applies. Differences: native secrets use names and static/oauth kinds; native OAuth uses authorizations, while compatible mcp_oauth creation and updates return 501; explicit allowed_hosts are required, with no unrestricted mode; Agent sessions reject nonempty vault_ids, so vault-backed MCP authentication is unavailable; application vault references return 501, including praxis_vault_ref bindings and secret writes with a vault source. Metadata labels do not attach credentials to either resource. Start with praxis.vault.vaults.create to create the containing vault.
Use your API Key as a Bearer credential to manage vaults and secrets at the address below. Secret values are write-only; no endpoint returns them.
https://api.deepraxis.ai/vault/v1
| Resource | Path |
|---|---|
| Vaults | /vault/v1/vaults |
| Secret | /vault/v1/vaults/{vault_id}/secrets |
| Templates | /vault/v1/templates |
| Authorizations | /vault/v1/authorizations |
Address a secret by its name or its vsec_ ID. Lists page with cursor and limit (default 50, at most 200); a null next_cursor means there is no next page.
The same vaults are also reachable through the Claude Managed Agents vaults API: Claude Managed Agents
Create and manage vaults, check availability, and read audit events without secret values.
Audit events are newest first. Filter by secret name or ID; an unknown secret returns an empty list. limit defaults to 50 and caps at 200; invalid limits or cursors return 400 INVALID_PARAMS. Events have no time-based expiry; archiving retains them, while deletion removes the resource's history and leaves a deletion record.
GET /vault/v1/vaults
| Parameter | Location | Description |
|---|---|---|
| cursor | query | next_cursor from the previous page. |
| limit | query | Items per page. (default: 50) (1–200) |
| include_archived | query | Include archived items. (default: false) |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| data | Vault[] | yes | Result items |
| data[].id | string | yes | Object ID |
| data[].type | "vault" | yes | Object type |
| data[].display_name | string | yes | Display name, 1–255 characters |
| data[].metadata | object | yes | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
| data[].status | "active" / "archived" | yes | Current status |
| data[].secret_count | integer | yes | Active secret count |
| data[].needs_reauthorization_count | integer | yes | OAuth secrets needing reauthorization after a failed refresh |
| data[].created_at | date-time | yes | Creation time |
| data[].updated_at | date-time | yes | Last update time |
| data[].archived_at | date-time / null | yes | Archive time, or null |
| next_cursor | string / null | yes | Next page cursor, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl "https://api.deepraxis.ai/vault/v1/vaults" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults
| Field | Type / enum | Required | Description |
|---|---|---|---|
| display_name | string | yes | Display name, 1–255 characters |
| metadata | object | no | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault" | yes | Object type |
| display_name | string | yes | Display name, 1–255 characters |
| metadata | object | yes | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
| status | "active" / "archived" | yes | Current status |
| secret_count | integer | yes | Active secret count |
| needs_reauthorization_count | integer | yes | OAuth secrets needing reauthorization after a failed refresh |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"display_name":"Agent credentials"}'POST /vault/v1/vaults:check
| Field | Type / enum | Required | Description |
|---|---|---|---|
| vault_ids | string[] | yes | Vault IDs to check (at most 50) |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| data | object[] | yes | Result items |
| data[].vault_id | string | yes | Vault ID |
| data[].status | "ok" / "not_found" / "archived" | yes | Current status |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults:check" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"vault_ids\":[\"${VAULT_ID}\"]}"GET /vault/v1/vaults/{vault_id}
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault" | yes | Object type |
| display_name | string | yes | Display name, 1–255 characters |
| metadata | object | yes | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
| status | "active" / "archived" | yes | Current status |
| secret_count | integer | yes | Active secret count |
| needs_reauthorization_count | integer | yes | OAuth secrets needing reauthorization after a failed refresh |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults/{vault_id}
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| display_name | string | no | Display name, 1–255 characters |
| metadata | object | no | Merge by key: strings upsert, null deletes, omitted keys remain; up to 16 caller labels |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault" | yes | Object type |
| display_name | string | yes | Display name, 1–255 characters |
| metadata | object | yes | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
| status | "active" / "archived" | yes | Current status |
| secret_count | integer | yes | Active secret count |
| needs_reauthorization_count | integer | yes | OAuth secrets needing reauthorization after a failed refresh |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata":{"team":"growth"}}'DELETE /vault/v1/vaults/{vault_id}
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_deleted" | yes | Object type |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
curl -X DELETE "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults/{vault_id}/archive
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault" | yes | Object type |
| display_name | string | yes | Display name, 1–255 characters |
| metadata | object | yes | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
| status | "active" / "archived" | yes | Current status |
| secret_count | integer | yes | Active secret count |
| needs_reauthorization_count | integer | yes | OAuth secrets needing reauthorization after a failed refresh |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/archive" \
-H "Authorization: Bearer $PRAXIS_API_KEY"GET /vault/v1/vaults/{vault_id}/events
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| secret | query | Only events of this secret (name or vsec_ ID). |
| cursor | query | next_cursor from the previous page. |
| limit | query | Items per page. (default: 50) (1–200) |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| data | VaultEvent[] | yes | Result items |
| data[].id | uuid | yes | Object ID |
| data[].type | "vault.created" / "vault.updated" / "vault.archived" / "vault.deleted" / "vault_secret.created" / "vault_secret.updated" / "vault_secret.archived" / "vault_secret.deleted" / "vault_secret.used" / "vault_secret.refreshed" / "vault_secret.refresh_failed" / "vault_authorization.completed" / "vault_authorization.failed" / "vault_authorization.expired" | yes | Object type |
| data[].secret_id | string / null | yes | Associated secret ID, or null |
| data[].secret_name | string / null | yes | Associated secret name |
| data[].at | date-time | yes | Event or error time |
| data[].detail | object / null | yes | Event facts, never secret values; changed lists updated fields |
| data[].detail.changed | string[] | no | Fields updated, such as value and allowed_hosts |
| next_cursor | string / null | yes | Next page cursor, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/events" \
-H "Authorization: Bearer $PRAXIS_API_KEY"| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault" | yes | Object type |
| display_name | string | yes | Display name, 1–255 characters |
| metadata | object | yes | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
| status | "active" / "archived" | yes | Current status |
| secret_count | integer | yes | Active secret count |
| needs_reauthorization_count | integer | yes | OAuth secrets needing reauthorization after a failed refresh |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| data | Vault[] | yes | Result items |
| data[].id | string | yes | Object ID |
| data[].type | "vault" | yes | Object type |
| data[].display_name | string | yes | Display name, 1–255 characters |
| data[].metadata | object | yes | Up to 16 caller labels; keys at most 64 characters, values at most 512 |
| data[].status | "active" / "archived" | yes | Current status |
| data[].secret_count | integer | yes | Active secret count |
| data[].needs_reauthorization_count | integer | yes | OAuth secrets needing reauthorization after a failed refresh |
| data[].created_at | date-time | yes | Creation time |
| data[].updated_at | date-time | yes | Last update time |
| data[].archived_at | date-time / null | yes | Archive time, or null |
| next_cursor | string / null | yes | Next page cursor, or null |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | uuid | yes | Object ID |
| type | "vault.created" / "vault.updated" / "vault.archived" / "vault.deleted" / "vault_secret.created" / "vault_secret.updated" / "vault_secret.archived" / "vault_secret.deleted" / "vault_secret.used" / "vault_secret.refreshed" / "vault_secret.refresh_failed" / "vault_authorization.completed" / "vault_authorization.failed" / "vault_authorization.expired" | yes | Object type |
| secret_id | string / null | yes | Associated secret ID, or null |
| secret_name | string / null | yes | Associated secret name |
| at | date-time | yes | Event or error time |
| detail | object / null | yes | Event facts, never secret values; changed lists updated fields |
| detail.changed | string[] | no | Fields updated, such as value and allowed_hosts |
Add, import and update write-only secrets; validation and refresh apply only to OAuth secrets.
Import replaces only the value of an existing name. Hosts change only from that line's own allowed_hosts, never from top-level defaults. New lines use their own hosts or the top-level defaults. Per-line failures appear in failed under HTTP 200 (including SECRET_TOO_LARGE, VAULT_LIMIT_EXCEEDED and INVALID_PARAMS); other lines are still written. Lookup by an invalid name returns 404 SECRET_NOT_FOUND.
GET /vault/v1/vaults/{vault_id}/secrets
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| cursor | query | next_cursor from the previous page. |
| limit | query | Items per page. (default: 50) (1–200) |
| include_archived | query | Include archived items. (default: false) |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| data | Secret[] | yes | Result items |
| data[].id | string | yes | Object ID |
| data[].type | "vault_secret" | yes | Object type |
| data[].vault_id | string | yes | Vault ID |
| data[].name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| data[].kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| data[].allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| data[].description | string / null | yes | Description; null clears it on update, omission preserves it |
| data[].metadata | object | yes | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| data[].status | "active" / "refreshing" / "refresh_failed" / "archived" | yes | Current status |
| data[].oauth | SecretOAuthSummary / null | yes | OAuth summary; null for static secrets |
| data[].oauth.expires_at | date-time / null | yes | Expiry time, or null |
| data[].oauth.last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| data[].oauth.next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| data[].oauth.scope | string / null | yes | Granted scope, or null |
| data[].oauth.last_error | object / null | yes | Last refresh failure, or null |
| data[].oauth.last_error.code | string | yes | Stable error code |
| data[].oauth.last_error.message | string | yes | Human-readable error message |
| data[].oauth.last_error.at | date-time | yes | Event or error time |
| data[].version | integer | yes | Increments each time the value changes |
| data[].last_used_at | date-time / null | yes | Last use time, or null |
| data[].created_at | date-time | yes | Creation time |
| data[].updated_at | date-time | yes | Last update time |
| data[].archived_at | date-time / null | yes | Archive time, or null |
| next_cursor | string / null | yes | Next page cursor, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults/{vault_id}/secrets
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| value | string | yes | Write-only secret value, at most 16 KiB |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | no | Description; null clears it on update, omission preserves it |
| metadata | object | no | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| template_id | "github" / "openai" / "anthropic" / "stripe" | no | Static template ID only; recorded as metadata.template |
| kind | "static" | no | Must be static; create OAuth secrets through authorization |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_secret" | yes | Object type |
| vault_id | string | yes | Vault ID |
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | yes | Description; null clears it on update, omission preserves it |
| metadata | object | yes | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| status | "active" / "refreshing" / "refresh_failed" / "archived" | yes | Current status |
| oauth | SecretOAuthSummary / null | yes | OAuth summary; null for static secrets |
| oauth.expires_at | date-time / null | yes | Expiry time, or null |
| oauth.last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| oauth.next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| oauth.scope | string / null | yes | Granted scope, or null |
| oauth.last_error | object / null | yes | Last refresh failure, or null |
| oauth.last_error.code | string | yes | Stable error code |
| oauth.last_error.message | string | yes | Human-readable error message |
| oauth.last_error.at | date-time | yes | Event or error time |
| version | integer | yes | Increments each time the value changes |
| last_used_at | date-time / null | yes | Last use time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
| SECRET_CONFLICT | 409 | Name already exists on creation; rename or update the existing secret | validation_failure | none | no |
| VAULT_LIMIT_EXCEEDED | 400 | Active-secret limit exceeded; remove unused secrets | validation_failure | none | no |
| SECRET_TOO_LARGE | 413 | Value exceeds 16384 bytes; reduce its size | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"GITHUB_TOKEN","value":"ghp_example","allowed_hosts":["api.github.com"]}'POST /vault/v1/vaults/{vault_id}/secrets:import
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| lines | ImportLine[] | no | ImportLine entries |
| lines[].name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| lines[].value | string | yes | Write-only secret value, at most 16 KiB |
| lines[].allowed_hosts | string[] | no | New entries use line hosts or import defaults; replacements change hosts only with explicit per-line allowed_hosts |
| dotenv | string | no | KEY=VALUE lines; provide exactly one of dotenv or lines |
| allowed_hosts | string[] | no | New entries use line hosts or import defaults; replacements change hosts only with explicit per-line allowed_hosts |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| created | string[] | yes | Created secret names |
| replaced | string[] | yes | Replaced secret names |
| failed | object[] | yes | Failed import lines |
| failed[].line | integer | yes | Failed line number, starting at 1 |
| failed[].name | string / null | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| failed[].code | "VAULT_NOT_FOUND" / "SECRET_NOT_FOUND" / "AUTHORIZATION_NOT_FOUND" / "SECRET_CONFLICT" / "VAULT_INVALID_STATE" / "VAULT_LIMIT_EXCEEDED" / "INVALID_PARAMS" / "SECRET_KIND_MISMATCH" / "VALIDATE_UNSUPPORTED" / "SECRET_TOO_LARGE" / "RATE_LIMITED" / "AUTHORIZATION_EXPIRED" / "OAUTH_DISCOVERY_FAILED" / "OAUTH_REGISTRATION_UNSUPPORTED" / "OAUTH_ISSUER_MISMATCH" / "OAUTH_STATE_INVALID" / "OAUTH_EXCHANGE_FAILED" / "NOT_IMPLEMENTED" | yes | Stable error code |
| failed[].message | string | yes | Human-readable error message |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets:import" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"dotenv":"OPENAI_API_KEY=sk-example\nLINEAR_API_KEY=lin_example","allowed_hosts":["api.openai.com","api.linear.app"]}'GET /vault/v1/vaults/{vault_id}/secrets/{secret}
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| secret | path | Secret name, or its vsec_ ID. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_secret" | yes | Object type |
| vault_id | string | yes | Vault ID |
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | yes | Description; null clears it on update, omission preserves it |
| metadata | object | yes | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| status | "active" / "refreshing" / "refresh_failed" / "archived" | yes | Current status |
| oauth | SecretOAuthSummary / null | yes | OAuth summary; null for static secrets |
| oauth.expires_at | date-time / null | yes | Expiry time, or null |
| oauth.last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| oauth.next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| oauth.scope | string / null | yes | Granted scope, or null |
| oauth.last_error | object / null | yes | Last refresh failure, or null |
| oauth.last_error.code | string | yes | Stable error code |
| oauth.last_error.message | string | yes | Human-readable error message |
| oauth.last_error.at | date-time | yes | Event or error time |
| version | integer | yes | Increments each time the value changes |
| last_used_at | date-time / null | yes | Last use time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults/{vault_id}/secrets/{secret}
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| secret | path | Secret name, or its vsec_ ID. |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| value | string | no | Write-only secret value, at most 16 KiB |
| allowed_hosts | string[] | no | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | no | Description; null clears it on update, omission preserves it |
| metadata | object | no | Merge by key: strings upsert, null deletes, omitted keys remain; source and template are reserved |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_secret" | yes | Object type |
| vault_id | string | yes | Vault ID |
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | yes | Description; null clears it on update, omission preserves it |
| metadata | object | yes | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| status | "active" / "refreshing" / "refresh_failed" / "archived" | yes | Current status |
| oauth | SecretOAuthSummary / null | yes | OAuth summary; null for static secrets |
| oauth.expires_at | date-time / null | yes | Expiry time, or null |
| oauth.last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| oauth.next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| oauth.scope | string / null | yes | Granted scope, or null |
| oauth.last_error | object / null | yes | Last refresh failure, or null |
| oauth.last_error.code | string | yes | Stable error code |
| oauth.last_error.message | string | yes | Human-readable error message |
| oauth.last_error.at | date-time | yes | Event or error time |
| version | integer | yes | Increments each time the value changes |
| last_used_at | date-time / null | yes | Last use time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
| SECRET_TOO_LARGE | 413 | Value exceeds 16384 bytes; reduce its size | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"value":"ghp_rotated"}'DELETE /vault/v1/vaults/{vault_id}/secrets/{secret}
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| secret | path | Secret name, or its vsec_ ID. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_secret_deleted" | yes | Object type |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
curl -X DELETE "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults/{vault_id}/secrets/{secret}/archive
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| secret | path | Secret name, or its vsec_ ID. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_secret" | yes | Object type |
| vault_id | string | yes | Vault ID |
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | yes | Description; null clears it on update, omission preserves it |
| metadata | object | yes | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| status | "active" / "refreshing" / "refresh_failed" / "archived" | yes | Current status |
| oauth | SecretOAuthSummary / null | yes | OAuth summary; null for static secrets |
| oauth.expires_at | date-time / null | yes | Expiry time, or null |
| oauth.last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| oauth.next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| oauth.scope | string / null | yes | Granted scope, or null |
| oauth.last_error | object / null | yes | Last refresh failure, or null |
| oauth.last_error.code | string | yes | Stable error code |
| oauth.last_error.message | string | yes | Human-readable error message |
| oauth.last_error.at | date-time | yes | Event or error time |
| version | integer | yes | Increments each time the value changes |
| last_used_at | date-time / null | yes | Last use time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN/archive" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults/{vault_id}/secrets/{secret}/validate
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| secret | path | Secret name, or its vsec_ ID. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| type | "vault_secret_validation" | yes | Object type |
| secret_id | string | yes | Associated secret ID, or null |
| vault_id | string | yes | Vault ID |
| validated_at | date-time | yes | Validation time |
| has_refresh_token | boolean | yes | Whether a refresh token is stored |
| status | "valid" / "invalid" / "unknown" | yes | Current status |
| probe | object | yes | Resource probe |
| probe.method | "GET" | yes | Probe method, currently GET |
| probe.http_response | HttpCapture / null | yes | HTTP response summary, or null when no response was received |
| probe.http_response.status_code | integer | yes | HTTP status code |
| probe.http_response.content_type | string / null | yes | Response content type, or null |
| probe.http_response.body | string | yes | Redacted response body |
| probe.http_response.body_truncated | boolean | yes | Whether the body was truncated |
| refresh | object | yes | Refresh attempt |
| refresh.status | "succeeded" / "failed" / "connect_error" / "no_refresh_token" / "skipped" | yes | Current status |
| refresh.http_response | HttpCapture / null | yes | HTTP response summary, or null when no response was received |
| refresh.http_response.status_code | integer | yes | HTTP status code |
| refresh.http_response.content_type | string / null | yes | Response content type, or null |
| refresh.http_response.body | string | yes | Redacted response body |
| refresh.http_response.body_truncated | boolean | yes | Whether the body was truncated |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
| VALIDATE_UNSUPPORTED | 400 | Validating a static secret; only OAuth secrets support validation | validation_failure | none | no |
| RATE_LIMITED | 429 | Authorization or validation minute quota exceeded; wait for the next window | rate_limit | wait_then_retry | yes |
OAuth secrets only. Complete authorization and set OAUTH_SECRET_ID to its secret_id before running this example; do not use a static secret.
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/${OAUTH_SECRET_ID}/validate" \
-H "Authorization: Bearer $PRAXIS_API_KEY"POST /vault/v1/vaults/{vault_id}/secrets/{secret}/refresh
| Parameter | Location | Description |
|---|---|---|
| vault_id | path | ID of the vault in your account, returned when the vault is created. |
| secret | path | Secret name, or its vsec_ ID. |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| reason | "unauthorized" | no | unauthorized: the resource returned HTTP 401 |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_secret" | yes | Object type |
| vault_id | string | yes | Vault ID |
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | yes | Description; null clears it on update, omission preserves it |
| metadata | object | yes | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| status | "active" / "refreshing" / "refresh_failed" / "archived" | yes | Current status |
| oauth | SecretOAuthSummary / null | yes | OAuth summary; null for static secrets |
| oauth.expires_at | date-time / null | yes | Expiry time, or null |
| oauth.last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| oauth.next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| oauth.scope | string / null | yes | Granted scope, or null |
| oauth.last_error | object / null | yes | Last refresh failure, or null |
| oauth.last_error.code | string | yes | Stable error code |
| oauth.last_error.message | string | yes | Human-readable error message |
| oauth.last_error.at | date-time | yes | Event or error time |
| version | integer | yes | Increments each time the value changes |
| last_used_at | date-time / null | yes | Last use time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| SECRET_KIND_MISMATCH | 400 | Refreshing a static secret or another kind mismatch; use an OAuth secret | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
OAuth secrets only. Complete authorization and set OAUTH_SECRET_ID to its secret_id before running this example; do not use a static secret.
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/${OAUTH_SECRET_ID}/refresh" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"unauthorized"}'| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_secret" | yes | Object type |
| vault_id | string | yes | Vault ID |
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| description | string / null | yes | Description; null clears it on update, omission preserves it |
| metadata | object | yes | Up to 16 caller labels. System keys source and template are reserved and excluded from that limit |
| status | "active" / "refreshing" / "refresh_failed" / "archived" | yes | Current status |
| oauth | SecretOAuthSummary / null | yes | OAuth summary; null for static secrets |
| oauth.expires_at | date-time / null | yes | Expiry time, or null |
| oauth.last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| oauth.next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| oauth.scope | string / null | yes | Granted scope, or null |
| oauth.last_error | object / null | yes | Last refresh failure, or null |
| oauth.last_error.code | string | yes | Stable error code |
| oauth.last_error.message | string | yes | Human-readable error message |
| oauth.last_error.at | date-time | yes | Event or error time |
| version | integer | yes | Increments each time the value changes |
| last_used_at | date-time / null | yes | Last use time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| archived_at | date-time / null | yes | Archive time, or null |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| expires_at | date-time / null | yes | Expiry time, or null |
| last_refreshed_at | date-time / null | yes | Last refresh time, or null |
| next_refresh_at | date-time / null | yes | Next scheduled refresh, or null |
| scope | string / null | yes | Granted scope, or null |
| last_error | object / null | yes | Last refresh failure, or null |
| last_error.code | string | yes | Stable error code |
| last_error.message | string | yes | Human-readable error message |
| last_error.at | date-time | yes | Event or error time |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| value | string | yes | Write-only secret value, at most 16 KiB |
| allowed_hosts | string[] | no | New entries use line hosts or import defaults; replacements change hosts only with explicit per-line allowed_hosts |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| created | string[] | yes | Created secret names |
| replaced | string[] | yes | Replaced secret names |
| failed | object[] | yes | Failed import lines |
| failed[].line | integer | yes | Failed line number, starting at 1 |
| failed[].name | string / null | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| failed[].code | "VAULT_NOT_FOUND" / "SECRET_NOT_FOUND" / "AUTHORIZATION_NOT_FOUND" / "SECRET_CONFLICT" / "VAULT_INVALID_STATE" / "VAULT_LIMIT_EXCEEDED" / "INVALID_PARAMS" / "SECRET_KIND_MISMATCH" / "VALIDATE_UNSUPPORTED" / "SECRET_TOO_LARGE" / "RATE_LIMITED" / "AUTHORIZATION_EXPIRED" / "OAUTH_DISCOVERY_FAILED" / "OAUTH_REGISTRATION_UNSUPPORTED" / "OAUTH_ISSUER_MISMATCH" / "OAUTH_STATE_INVALID" / "OAUTH_EXCHANGE_FAILED" / "NOT_IMPLEMENTED" | yes | Stable error code |
| failed[].message | string | yes | Human-readable error message |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| type | "vault_secret_validation" | yes | Object type |
| secret_id | string | yes | Associated secret ID, or null |
| vault_id | string | yes | Vault ID |
| validated_at | date-time | yes | Validation time |
| has_refresh_token | boolean | yes | Whether a refresh token is stored |
| status | "valid" / "invalid" / "unknown" | yes | Current status |
| probe | object | yes | Resource probe |
| probe.method | "GET" | yes | Probe method, currently GET |
| probe.http_response | HttpCapture / null | yes | HTTP response summary, or null when no response was received |
| probe.http_response.status_code | integer | yes | HTTP status code |
| probe.http_response.content_type | string / null | yes | Response content type, or null |
| probe.http_response.body | string | yes | Redacted response body |
| probe.http_response.body_truncated | boolean | yes | Whether the body was truncated |
| refresh | object | yes | Refresh attempt |
| refresh.status | "succeeded" / "failed" / "connect_error" / "no_refresh_token" / "skipped" | yes | Current status |
| refresh.http_response | HttpCapture / null | yes | HTTP response summary, or null when no response was received |
| refresh.http_response.status_code | integer | yes | HTTP status code |
| refresh.http_response.content_type | string / null | yes | Response content type, or null |
| refresh.http_response.body | string | yes | Redacted response body |
| refresh.http_response.body_truncated | boolean | yes | Whether the body was truncated |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| status_code | integer | yes | HTTP status code |
| content_type | string / null | yes | Response content type, or null |
| body | string | yes | Redacted response body |
| body_truncated | boolean | yes | Whether the body was truncated |
Find template IDs, secret names, kinds and allowed hosts for common services.
| template_id | kind | Service |
|---|---|---|
| github | static | GitHub (api.github.com, uploads.github.com) |
| openai | static | OpenAI |
| anthropic | static | Anthropic |
| stripe | static | Stripe |
| linear | oauth | Linear (CIMD) |
| atlassian | oauth | Atlassian (DCR) |
GET /vault/v1/templates
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| data | VaultTemplate[] | yes | Result items |
| data[].id | string | yes | Object ID |
| data[].display_name | string | yes | Display name, 1–255 characters |
| data[].kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| data[].name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| data[].allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| data[].value_hint | string / null | yes | Suggested value format, or null |
A missing or invalid API Key returns 401 UNAUTHENTICATED. No additional domain errors.
curl "https://api.deepraxis.ai/vault/v1/templates" \
-H "Authorization: Bearer $PRAXIS_API_KEY"| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| display_name | string | yes | Display name, 1–255 characters |
| kind | "static" / "oauth" | yes | static: supplied value; oauth: authorized and refreshed by the platform |
| name | string | yes | Secret name: 1–128 uppercase letters, digits or underscores; starts with a letter or underscore |
| allowed_hosts | string[] | yes | 1–16 hosts, public IPv4 addresses or *.example.com (excluding the apex). Rejects IPv6, single-label hosts, localhost, *.internal, platform domains and loopback/link-local/private/CGNAT IPv4; normalized and deduplicated |
| value_hint | string / null | yes | Suggested value format, or null |
Authorize third-party services and manage one-time links and return URLs.
Authorization produces a secret of kind oauth for services that support OAuth. Create an authorization and give connect_url to the end user; once they approve on the confirmation page and on the service, the secret is written to the vault and the platform keeps it refreshed. The confirmation page, the callback and the client metadata need no API Key.
POST /vault/v1/authorizations
| Field | Type / enum | Required | Description |
|---|---|---|---|
| vault_id | string | yes | Vault ID |
| template_id | "linear" / "atlassian" | no | OAuth template ID; provide exactly one of template_id or resource_url |
| resource_url | string | no | Resource URL to authorize |
| return_url | string | no | Return URL; must be on the account allowlist |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_authorization" | yes | Object type |
| vault_id | string | yes | Vault ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | yes | Current status |
| resource | string | yes | Authorized resource URL |
| secret_name | string | yes | Associated secret name |
| connect_url | string | yes | One-time confirmation page, valid for 30 minutes |
| client_registration | "cimd" / "dcr" / null | yes | cimd: Client ID Metadata Document; dcr: Dynamic Client Registration; null before registration |
| secret_id | string / null | yes | Associated secret ID, or null |
| error | object / null | yes | Failure details, or null |
| error.code | string | yes | Stable error code |
| error.message | string | yes | Human-readable error message |
| expires_at | date-time | yes | Expiry time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
| RATE_LIMITED | 429 | Authorization or validation minute quota exceeded; wait for the next window | rate_limit | wait_then_retry | yes |
| OAUTH_DISCOVERY_FAILED | 400 | OAuth metadata discovery failed; check the resource URL | validation_failure | continue_from_problem | no |
| OAUTH_REGISTRATION_UNSUPPORTED | 400 | Provider does not accept automatic client registration; add credentials manually | validation_failure | continue_from_problem | no |
| OAUTH_ISSUER_MISMATCH | 400 | Authorization issuer differs from the expected issuer; check the service URL | provider_upstream | retry_from_user | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/authorizations" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"vault_id\":\"${VAULT_ID}\",\"template_id\":\"linear\"}"GET /vault/v1/authorizations/{authorization_id}
| Parameter | Location | Description |
|---|---|---|
| authorization_id | path | ID of the authorization in your account, returned when authorization is created. |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_authorization" | yes | Object type |
| vault_id | string | yes | Vault ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | yes | Current status |
| resource | string | yes | Authorized resource URL |
| secret_name | string | yes | Associated secret name |
| connect_url | string | yes | One-time confirmation page, valid for 30 minutes |
| client_registration | "cimd" / "dcr" / null | yes | cimd: Client ID Metadata Document; dcr: Dynamic Client Registration; null before registration |
| secret_id | string / null | yes | Associated secret ID, or null |
| error | object / null | yes | Failure details, or null |
| error.code | string | yes | Stable error code |
| error.message | string | yes | Human-readable error message |
| expires_at | date-time | yes | Expiry time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
curl "https://api.deepraxis.ai/vault/v1/authorizations/${AUTHORIZATION_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"GET /vault/v1/settings/return_urls
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |
A missing or invalid API Key returns 401 UNAUTHENTICATED. No additional domain errors.
curl "https://api.deepraxis.ai/vault/v1/settings/return_urls" \
-H "Authorization: Bearer $PRAXIS_API_KEY"PUT /vault/v1/settings/return_urls
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl -X PUT "https://api.deepraxis.ai/vault/v1/settings/return_urls" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://app.example.com/connected"]}'GET /vault/v1/authorizations/callback · No API Key
| Parameter | Location | Description |
|---|---|---|
| code | query | Authorization code from the provider |
| state | query | Single-use authorization state |
| error | query | Provider denial code |
| iss | query | Authorization server issuer |
text/html
Confirmation or result page displayed by the browser.
The Location header redirects to the provider or an allowed return URL.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| OAUTH_STATE_INVALID | 400 | Callback state missing, invalid or replayed; start authorization again | validation_failure | none | no |
| OAUTH_ISSUER_MISMATCH | 400 | Authorization issuer differs from the expected issuer; check the service URL | provider_upstream | retry_from_user | no |
| OAUTH_EXCHANGE_FAILED | 502 | Provider rejected the authorization-code exchange; authorize again | provider_upstream | retry_from_user | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
Returns 302 when return_url is set; otherwise returns an HTTP 200 result page.
curl "https://api.deepraxis.ai/vault/v1/authorizations/callback"GET /vault/v1/oauth/client.json · No API Key
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| client_id | string | yes | Client metadata URL |
| client_name | string | yes | Client display name |
| redirect_uris | string[] | yes | Allowed OAuth callback URLs |
| token_endpoint_auth_method | "none" | yes | Token endpoint authentication method |
| grant_types | "authorization_code" / "refresh_token"[] | no | Supported grant types |
| response_types | "code"[] | no | Supported authorization response types |
No additional domain errors.
curl "https://api.deepraxis.ai/vault/v1/oauth/client.json"GET /vault/v1/connect/{token} · No API Key
| Parameter | Location | Description |
|---|---|---|
| token | path | One-time token from connect_url. |
text/html
Confirmation or result page displayed by the browser.
text/html
Confirmation or result page displayed by the browser.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
Invalid links return 404; expired or consumed links return 410, as HTML pages.
curl "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}"POST /vault/v1/connect/{token}/continue · No API Key
| Parameter | Location | Description |
|---|---|---|
| token | path | One-time token from connect_url. |
The Location header redirects to the provider or an allowed return URL.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
| OAUTH_DISCOVERY_FAILED | 400 | OAuth metadata discovery failed; check the resource URL | validation_failure | continue_from_problem | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/continue"POST /vault/v1/connect/{token}/deny · No API Key
| Parameter | Location | Description |
|---|---|---|
| token | path | One-time token from connect_url. |
text/html
Confirmation or result page displayed by the browser.
The Location header redirects to the provider or an allowed return URL.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
Returns 302 when return_url is set; otherwise returns an HTTP 200 result page.
curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/deny"| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_authorization" | yes | Object type |
| vault_id | string | yes | Vault ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | yes | Current status |
| resource | string | yes | Authorized resource URL |
| secret_name | string | yes | Associated secret name |
| connect_url | string | yes | One-time confirmation page, valid for 30 minutes |
| client_registration | "cimd" / "dcr" / null | yes | cimd: Client ID Metadata Document; dcr: Dynamic Client Registration; null before registration |
| secret_id | string / null | yes | Associated secret ID, or null |
| error | object / null | yes | Failure details, or null |
| error.code | string | yes | Stable error code |
| error.message | string | yes | Human-readable error message |
| expires_at | date-time | yes | Expiry time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |
Every error response has the shape below; code is the stable error code and message is for people.
{
"request_id": "req_example",
"error": {
"code": "SECRET_CONFLICT",
"message": "A secret named GITHUB_TOKEN already exists",
"kind": "validation_failure",
"recovery": "none",
"retryable": false
}
}Error bodies include request_id for tracing. Compatibility endpoints use the following shape; 409 maps to conflict_error, and non-retryable errors carry x-should-retry: false.
{
"type": "error",
"error": {
"type": "conflict_error",
"message": "A credential with this name already exists"
},
"request_id": "req_example"
}| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| SECRET_CONFLICT | 409 | Name already exists on creation; rename or update the existing secret | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| VAULT_LIMIT_EXCEEDED | 400 | Active-secret limit exceeded; remove unused secrets | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
| SECRET_KIND_MISMATCH | 400 | Refreshing a static secret or another kind mismatch; use an OAuth secret | validation_failure | none | no |
| VALIDATE_UNSUPPORTED | 400 | Validating a static secret; only OAuth secrets support validation | validation_failure | none | no |
| SECRET_TOO_LARGE | 413 | Value exceeds 16384 bytes; reduce its size | validation_failure | none | no |
| RATE_LIMITED | 429 | Authorization or validation minute quota exceeded; wait for the next window | rate_limit | wait_then_retry | yes |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
| OAUTH_DISCOVERY_FAILED | 400 | OAuth metadata discovery failed; check the resource URL | validation_failure | continue_from_problem | no |
| OAUTH_REGISTRATION_UNSUPPORTED | 400 | Provider does not accept automatic client registration; add credentials manually | validation_failure | continue_from_problem | no |
| OAUTH_ISSUER_MISMATCH | 400 | Authorization issuer differs from the expected issuer; check the service URL | provider_upstream | retry_from_user | no |
| OAUTH_STATE_INVALID | 400 | Callback state missing, invalid or replayed; start authorization again | validation_failure | none | no |
| OAUTH_EXCHANGE_FAILED | 502 | Provider rejected the authorization-code exchange; authorize again | provider_upstream | retry_from_user | no |
| NOT_IMPLEMENTED | 501 | Capability unavailable; use a documented alternative | execution_failed | none | no |