# Vaults (/en/docs/api/native/vault/vaults)



Create and manage vaults, check availability, and read audit events without secret values.

[Guide →](/en/docs/developers/services/vault/quickstart)

[Base URL and authentication](/en/docs/api/native/vault)

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.

## List vaults [#list-vaults]

`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) |

### Response [#response]

#### HTTP 200 [#http-200]

**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 |

### Error responses [#error-responses]

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 |

```bash
curl "https://api.deepraxis.ai/vault/v1/vaults" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## Create vault [#create-vault]

`POST /vault/v1/vaults`

### Request body [#request-body]

| 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 |

### Response [#response-1]

#### HTTP 200 [#http-200-1]

**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 |

### Error responses [#error-responses-1]

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 |

```bash
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"}'
```

## Check vaults [#check-vaults]

`POST /vault/v1/vaults:check`

### Request body [#request-body-1]

| Field | Type / enum | Required | Description |
| --- | --- | --- | --- |
| vault_ids | string[] | yes | Vault IDs to check (at most 50) |

### Response [#response-2]

#### HTTP 200 [#http-200-2]

**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 |

### Error responses [#error-responses-2]

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 |

```bash
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 [#get-vault]

`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. |

### Response [#response-3]

#### HTTP 200 [#http-200-3]

**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 |

### Error responses [#error-responses-3]

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 |

```bash
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## Update vault [#update-vault]

`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. |

### Request body [#request-body-2]

| 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 |

### Response [#response-4]

#### HTTP 200 [#http-200-4]

**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 |

### Error responses [#error-responses-4]

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 |

```bash
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 [#delete-vault]

`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. |

### Response [#response-5]

#### HTTP 200 [#http-200-5]

**application/json**

| Field | Type / enum | Required | Description |
| --- | --- | --- | --- |
| id | string | yes | Object ID |
| type | "vault_deleted" | yes | Object type |

### Error responses [#error-responses-5]

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 |

```bash
curl -X DELETE "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## Archive vault [#archive-vault]

`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. |

### Response [#response-6]

#### HTTP 200 [#http-200-6]

**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 |

### Error responses [#error-responses-6]

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 |

```bash
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## List events [#list-events]

`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) |

### Response [#response-7]

#### HTTP 200 [#http-200-7]

**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 |

### Error responses [#error-responses-7]

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 |

```bash
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/events" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## Vault [#vault]

| 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 |

## VaultPage [#vaultpage]

| 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 |

## VaultEvent [#vaultevent]

| 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 |