<!-- llms.txt: https://workos.com/llms.txt -->

# Encrypted object

Represents an encrypted object stored by Vault.

:::code-group{title="Object"}

```json language="curl"
{
  "id": "secret_51B0AC67C2FB4247AC5ABDDD3C701BDC",
  "metadata": {
    "id": "secret_51B0AC67C2FB4247AC5ABDDD3C701BDC",
    "environment_id": "environment_example_23456789",
    "context": {
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT"
    },
    "key_id": "e2084ada-50c1-5f9a-b1c7-fa868d506e5a",
    "updated_at": "2025-02-21T12:04:09.165291Z",
    "updated_by": {
      "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
      "name": "Marcelina Davis"
    },
    "version_id": "Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X"
  },
  "name": "secret-name",
  "value": "my secret value"
}
```

```js language="js"
const object = {
  id: 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC',
  metadata: {
    id: 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC',
    environmentId: 'environment_example_23456789',
    context: {
      organization_id: 'org_01EHZNVPK3SFK441A1RGBFSHRT',
    },
    keyId: 'e2084ada-50c1-5f9a-b1c7-fa868d506e5a',
    updatedAt: '2025-02-21T12:04:09.165291Z',
    updatedBy: {
      id: 'user_01E4ZCR3C56J083X43JQXF3JK5',
      name: 'Marcelina Davis',
    },
    versionId: 'Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X',
  },
  name: 'secret-name',
  value: 'my secret value',
};
```

```py language="python"
from workos.types.vault import VaultObject, ObjectMetadata, KeyContext, ObjectUpdateBy

vault_object = VaultObject(
    id="secret_51B0AC67C2FB4247AC5ABDDD3C701BDC",
    metadata=ObjectMetadata(
        id="secret_51B0AC67C2FB4247AC5ABDDD3C701BDC",
        environment_id="environment_example_23456789",
        context=KeyContext(
            organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT",
        ),
        key_id="e2084ada-50c1-5f9a-b1c7-fa868d506e5a",
        updated_at="2025-02-21T12:04:09.165Z",
        updated_by=ObjectUpdateBy(
            id="user_01E4ZCR3C56J083X43JQXF3JK5",
            name="Marcelina Davis",
        ),
        version_id="Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X",
    ),
    name="secret-name",
    value="my secret value",
)
```

```go language="go"
package main

import (
	"fmt"

	"github.com/workos/workos-go/v10"
)

func main() {
	object := workos.VaultObject{
		ID: "secret_51B0AC67C2FB4247AC5ABDDD3C701BDC",
		Metadata: &workos.ObjectMetadata{
			ID:            "secret_51B0AC67C2FB4247AC5ABDDD3C701BDC",
			EnvironmentID: "environment_example_23456789",
			Context: map[string]string{
				"organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
			},
			KeyID:     "e2084ada-50c1-5f9a-b1c7-fa868d506e5a",
			UpdatedAt: "2024-07-01T19:07:33.155Z",
			UpdatedBy: &workos.Actor{
				ID:   "user_01E4ZCR3C56J083X43JQXF3JK5",
				Name: "Marcelina Davis",
			},
			VersionID: workos.String("Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X"),
		},
		Name:  "secret-name",
		Value: "my secret value",
	}

	fmt.Printf("%+v\n", object)
}
```

:::

## Create an object

Encrypt and store a new key-value object.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/vault/v1/kv" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "key_context": {
            "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"
        },
        "name": "my-secret",
        "value": "s3cr3t-v4lu3"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.createObject({
  name: 'secret-name',
  value: 'my secret value',
  context: { organizationId: 'org_01EHZNVPK3SFK441A1RGBFSHRT' },
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.create_kv(
  key_context: { organization_id: "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P" },
  name: "my-secret",
  value: "s3cr3t-v4lu3"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.create_kv(
    key_context={"organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"},
    name="my-secret",
    value="s3cr3t-v4lu3",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().CreateKv(context.Background(), &workos.VaultCreateKvParams{
		KeyContext: map[string]any{"organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"},
		Name:       "my-secret",
		Value:      "s3cr3t-v4lu3",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->vault()
    ->createKv(
        keyContext: ["organization_id" => "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"],
        name: "my-secret",
        value: "s3cr3t-v4lu3",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.vault.VaultApi.CreateKvOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateKvOptions options =
    CreateKvOptions.builder()
        .keyContext(Map.of("organization_id", "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"))
        .name("my-secret")
        .value("s3cr3t-v4lu3")
        .build();

workos.vault.createKv(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.CreateKvAsync(new VaultCreateKvOptions {
    KeyContext =
        new Dictionary<string, object> {
            { "organization_id", "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P" },
        },
    Name = "my-secret",
    Value = "s3cr3t-v4lu3",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::vault::CreateKvParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .create_kv(
            CreateKvParams {
                key_context: serde_json::json!({ "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P" }),
                name: "my-secret".into(),
                value: "s3cr3t-v4lu3".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "context": {
    "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"
  },
  "environment_id": "environment_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key_id": "bf65e326-43a0-4b20-88c4-07ff3de5434c",
  "updated_at": "2024-06-15T10:30:00Z",
  "updated_by": {
    "id": "key_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
    "name": "My API Key"
  },
  "version_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd"
}
```

:::

## Delete an object

Delete an encrypted object.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/vault/v1/kv/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.deleteObject({
  id: 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.delete_kv(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.delete_kv(id_="a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().DeleteKv(context.Background(), "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->vault()->deleteKv(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.vault.deleteKv("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.DeleteKvAsync("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .delete_kv("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "name": "my-secret",
  "success": true
}
```

:::

## Read an object by name

Fetch and decrypt an object by its unique name.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/vault/v1/kv/name/my-secret" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.readObjectByName('my-secret-name');
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.get_name(name: "my-secret")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.get_name(name="my-secret")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().GetName(context.Background(), "my-secret")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->vault()->getName(name: "my-secret");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.vault.getName("my-secret");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.GetNameAsync("my-secret");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .get_name("my-secret")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {
    "context": {
      "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"
    },
    "environment_id": "environment_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key_id": "bf65e326-43a0-4b20-88c4-07ff3de5434c",
    "updated_at": "2024-06-15T10:30:00Z",
    "updated_by": {
      "id": "key_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
      "name": "My API Key"
    },
    "version_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd"
  },
  "name": "my-secret",
  "value": "s3cr3t-v4lu3"
}
```

:::

## Read an object by ID

Fetch and decrypt an object by its unique identifier.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/vault/v1/kv/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.readObject({
  id: 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.get_kv(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.get_kv(id_="a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().GetKv(context.Background(), "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->vault()->getKv(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.vault.getKv("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.GetKvAsync("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .get_kv("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {
    "context": {
      "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"
    },
    "environment_id": "environment_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key_id": "bf65e326-43a0-4b20-88c4-07ff3de5434c",
    "updated_at": "2024-06-15T10:30:00Z",
    "updated_by": {
      "id": "key_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
      "name": "My API Key"
    },
    "version_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd"
  },
  "name": "my-secret",
  "value": "s3cr3t-v4lu3"
}
```

:::

## List objects

List all encrypted objects with cursor-based pagination.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/vault/v1/kv" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.listObjects();
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.list_kv
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.list_kv()
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().ListKv(context.Background())
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->vault()->listKv();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.vault.listKv();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.ListKvAsync();
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .list_kv()
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "my-secret",
      "updated_at": "2024-06-15T10:30:00Z"
    }
  ],
  "list_metadata": {
    "after": "b21f3a8c-7e4d-4b1a-9c5e-2d8f6a7b3c4e",
    "before": "a10e2b7d-6c3f-4a2b-8d1e-3f9a5b8c7d6e"
  }
}
```

:::

## Describe an object

Fetch metadata for an object without decrypting it.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/vault/v1/kv/a1b2c3d4-e5f6-7890-abcd-ef1234567890/metadata" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.describeObject({
  id: 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.list_kv_metadata(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.list_kv_metadata(id_="a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().ListKvMetadata(context.Background(), "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->vault()->listKvMetadata(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.vault.listKvMetadata("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.ListKvMetadataAsync("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .list_kv_metadata("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {
    "context": {
      "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"
    },
    "environment_id": "environment_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key_id": "bf65e326-43a0-4b20-88c4-07ff3de5434c",
    "updated_at": "2024-06-15T10:30:00Z",
    "updated_by": {
      "id": "key_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
      "name": "My API Key"
    },
    "version_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd"
  },
  "name": "my-secret"
}
```

:::

## Update an object

Update the value of an existing encrypted object.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/vault/v1/kv/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "value": "upd4t3d-v4lu3"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.updateObject({
  id: 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC',
  value: 'new value',
  versionCheck: 'Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.update_kv(
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  value: "upd4t3d-v4lu3"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.update_kv(
    id_="a1b2c3d4-e5f6-7890-abcd-ef1234567890", value="upd4t3d-v4lu3"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().UpdateKv(context.Background(), "a1b2c3d4-e5f6-7890-abcd-ef1234567890", &workos.VaultUpdateKvParams{
		Value: "upd4t3d-v4lu3",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->vault()
    ->updateKv(
        id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        value: "upd4t3d-v4lu3",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.vault.VaultApi.UpdateKvOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateKvOptions options = UpdateKvOptions.builder().value("upd4t3d-v4lu3").build();

workos.vault.updateKv("a1b2c3d4-e5f6-7890-abcd-ef1234567890", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.UpdateKvAsync("a1b2c3d4-e5f6-7890-abcd-ef1234567890", new VaultUpdateKvOptions {
    Value = "upd4t3d-v4lu3",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::vault::UpdateKvParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .update_kv(
            "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            UpdateKvParams {
                value: "upd4t3d-v4lu3".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {
    "context": {
      "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"
    },
    "environment_id": "environment_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key_id": "bf65e326-43a0-4b20-88c4-07ff3de5434c",
    "updated_at": "2024-06-15T10:30:00Z",
    "updated_by": {
      "id": "key_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
      "name": "My API Key"
    },
    "version_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd"
  },
  "name": "my-secret"
}
```

:::

# Object version

Represents a static version of an object stored by Vault.

:::code-group{title="Object Version"}

```json language="curl"
{
  "created_at": "2025-02-21T12:04:09.165291Z",
  "current_version": true,
  "etag": "\"62b747b941ceefd67dacc026724044e4\"",
  "id": "Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X",
  "size": 271
}
```

```js language="js"
const objectVersion = {
  createdAt: '2025-02-21T12:04:09.165291Z',
  currentVersion: true,
  etag: '"62b747b941ceefd67dacc026724044e4"',
  id: 'Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X',
  size: 271,
};
```

```py language="python"
from workos.types.vault import ObjectVersion

object_version = ObjectVersion(
    id="Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X",
    current_version=True,
    created_at="2025-02-21T12:04:09.165291Z",
)
```

```go language="go"
package main

import (
	"fmt"

	"github.com/workos/workos-go/v10"
)

func main() {
	objectVersion := workos.ObjectVersion{
		ID:             "Wq49AmJIR7QI0kSwfY9BZ6vNsOq6AO_X",
		CreatedAt:      "2024-07-01T19:07:33.155Z",
		CurrentVersion: true,
		Etag:           "\"62b747b941ceefd67dacc026724044e4\"",
		Size:           271,
	}

	fmt.Printf("%+v\n", objectVersion)
}
```

:::

## List object versions

Retrieve all versions for a specific object.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/vault/v1/kv/a1b2c3d4-e5f6-7890-abcd-ef1234567890/versions" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.vault.listObjectVersions({
  id: 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.vault.list_kv_versions(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.vault.list_kv_versions(id_="a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Vault().ListKvVersions(context.Background(), "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->vault()->listKvVersions(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.vault.listKvVersions("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Vault.ListKvVersionsAsync("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .vault()
        .list_kv_versions("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "data": [
    {
      "created_at": "2024-06-15T10:30:00Z",
      "current_version": true,
      "etag": "d41d8cd98f00b204e9800998ecf8427e",
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "size": 256
    }
  ],
  "list_metadata": {
    "after": "b21f3a8c-7e4d-4b1a-9c5e-2d8f6a7b3c4e",
    "before": "a10e2b7d-6c3f-4a2b-8d1e-3f9a5b8c7d6e"
  }
}
```

:::

### object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique string ID of the object. |
| `name` | string | Yes | Unique name of the object, used as the KV store key. |
| `value` | string | Yes | Plaintext data that will be stored in an encrypted format. |
| `metadata` | object | Yes |  |

### POST /vault/v1/kv

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key_context` | object | Yes | Map of values used to determine the encryption key. |
| `name` | string | Yes | Unique name for the object. |
| `value` | string | Yes | Plaintext data to encrypt and store. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `context` | object | Map of values used to determine the encryption key. |
| `environment_id` | string | Environment the object belongs to. |
| `id` | string | Unique identifier of the object. |
| `key_id` | string | Encryption key identifier. |
| `updated_at` | string | Timestamp of the last update. |
| `updated_by` | object | The user or API key that performed an action. |
| `version_id` | string | Current version identifier of the object. |

### DELETE /vault/v1/kv/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the object. |
| `version_check` | string | No | Expected current version for optimistic locking. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Name of the deleted object. |
| `success` | boolean | Whether the deletion succeeded. |

### GET /vault/v1/kv/name/{name}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Unique name of the object. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier of the object. |
| `metadata` | object | Metadata for a stored encrypted object. |
| `name` | string | Unique name of the object. |
| `value` | string | Decrypted plaintext value. |

### GET /vault/v1/kv/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the object. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier of the object. |
| `metadata` | object | Metadata for a stored encrypted object. |
| `name` | string | Unique name of the object. |
| `value` | string | Decrypted plaintext value. |

### GET /vault/v1/kv

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Upper limit on the number of objects to return. Defaults to `10`. |
| `before` | string | No | Cursor for the previous page of results. |
| `after` | string | No | Cursor for the next page of results. |
| `order` | "asc" \| "desc" | No | Sort direction for results. |
| `search` | string | No | Filter results by name or structured search JSON. |
| `updatedAfter` | string | No | ISO 8601 timestamp to filter by last modified time. |

### GET /vault/v1/kv/{id}/metadata

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the object. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier of the object. |
| `metadata` | object | Metadata for a stored encrypted object. |
| `name` | string | Unique name of the object. |

### PUT /vault/v1/kv/{id}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | Yes | New plaintext value. |
| `version_check` | string | No | ID of the expected current version for optimistic locking. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the object. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier of the object. |
| `metadata` | object | Metadata for a stored encrypted object. |
| `name` | string | Unique name of the object. |

### object_version

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique string ID of the version. |
| `current_version` | boolean | Yes | Boolean indicating whether this version is the default for the object. |
| `created_at` | string | Yes | ISO 8601 timestamp of when this version was created. |
| `size` | integer | Yes | Number of bytes of data stored in the object. |
| `etag` | string | Yes | A hash of the value of the object. |

### GET /vault/v1/kv/{id}/versions

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the object. |