Vault

The vault is a zero-knowledge encrypted credential store for your organization. Store API keys, login credentials, SSH keys, and other secrets: Inkbox never sees the plaintext. All encryption and decryption happens client-side in the SDK or console using your vault key.

How it works

Every secret stored in the vault is encrypted with your organization’s encryption key before it leaves the SDK. The server only ever sees ciphertext. To read secrets, you unlock the vault with your vault key, and the SDK or console decrypts everything locally. Two keys are involved:

Key	Purpose
`INKBOX_API_KEY`	Authenticates API requests (sent to server)
`INKBOX_VAULT_KEY`	Unlocks the vault for client-side decryption (never sent to server)

Each key resolves from the SDK/CLI argument, then its environment variable, then a ~/.inkbox/config file (api_key = ... / vault_key = ...) — handy for background or agent processes that don’t inherit your shell’s env.

Secret types

Each secret has a type that determines its payload structure:

Type	Fields	Use case
`login`	`password`, `username`, `email`, `url`, `notes`, `totp`	Website or service logins (with optional TOTP)
`api_key`	`api_key`, `endpoint`, `notes`	API keys and tokens
`key_pair`	`access_key`, `secret_key`, `endpoint`, `notes`	Access key and secret key pairs
`ssh_key`	`private_key`, `public_key`, `fingerprint`, `passphrase`, `notes`	SSH keys
`other`	`data`, `notes`	Freeform secrets

Open the SDK client

The SDK examples below share one client. Keep it open while you work through them. Choose your own vault key in place of the example value, or use your existing vault key. For this manual setup, leave INKBOX_VAULT_KEY and the vault_key entry in ~/.inkbox/config unset. A configured vault key makes the SDK attempt to unlock during construction, before a new vault exists.

import os
from inkbox import Inkbox

inkbox = Inkbox(api_key=os.environ["INKBOX_API_KEY"])
vault_key = "My-Str0ng-Vault-Key!"

import { Inkbox } from "@inkbox/sdk";

const inkbox = new Inkbox({ apiKey: process.env.INKBOX_API_KEY! });
const vaultKey = "My-Str0ng-Vault-Key!";

export INKBOX_API_KEY="ApiKey_..."

Initializing the vault

Initialize a vault once per organization. Your API key determines the organization. Initialization creates the vault, sets the primary vault key, and generates four recovery codes. Store the recovery codes securely when they are returned. If the vault already exists, continue to unlocking it with its current key.

if inkbox.vault.info() is None:
    result = inkbox.vault.initialize(vault_key)
    print(result.vault_id)
    print(result.recovery_codes)

if (await inkbox.vault.info() === null) {
  const result = await inkbox.vault.initialize(vaultKey);
  console.log(result.vaultId);
  console.log(result.recoveryCodes);
}

# Run once if your organization does not have a vault yet.
inkbox vault init --vault-key "My-Str0ng-Vault-Key!"

Unlocking the vault

Before you can read or write secrets, unlock the initialized vault with the same key. The SDK validates the key, fetches all encrypted secrets, and decrypts them locally.

unlocked = inkbox.vault.unlock(vault_key)
print(f"Unlocked {len(unlocked.secrets)} secrets")

const unlocked = await inkbox.vault.unlock(vaultKey);
console.log(`Unlocked ${unlocked.secrets.length} secrets`);

# Set this after initialization, using the same vault key.
export INKBOX_VAULT_KEY="My-Str0ng-Vault-Key!"

# Subsequent vault commands unlock automatically.
inkbox vault secrets

Creating secrets

Once unlocked, create secrets by specifying a name and a payload. Python uses payload dataclasses. TypeScript infers the secret type from the payload’s fields. The SDK encrypts the payload before sending it to the server.

from inkbox.vault import APIKeyPayload, LoginPayload

# Store an API key
unlocked.create_secret(
    name="LLM Production",
    description="Production API key for the primary model provider",
    payload=APIKeyPayload(
        api_key="example-api-key",
        endpoint="https://api.example.com/v1",
        notes="Rate limit: 10k RPM",
    ),
)

# Store a login credential
unlocked.create_secret(
    name="Dashboard Login",
    payload=LoginPayload(
        username="agent@example.com",
        password="s3cret!",
        url="https://dashboard.example.com",
    ),
)

// Store an API key
await unlocked.createSecret({
  name: "LLM Production",
  description: "Production API key for the primary model provider",
  payload: {
      apiKey: "example-api-key",
      endpoint: "https://api.example.com/v1",
      notes: "Rate limit: 10k RPM",
  },
});

// Store a login credential
await unlocked.createSecret({
  name: "Dashboard Login",
  payload: {
      username: "agent@example.com",
      password: "s3cret!",
      url: "https://dashboard.example.com",
  },
});

# Store an API key
inkbox vault create \
--name "LLM Production" \
--description "Production API key for the primary model provider" \
--type api_key \
--key "example-api-key" \
--endpoint "https://api.example.com/v1" \
--notes "Rate limit: 10k RPM"

# Store a login credential
inkbox vault create \
--name "Dashboard Login" \
--type login \
--username "agent@example.com" \
--password "s3cret!" \
--url "https://dashboard.example.com"

Reading secrets

Access all decrypted secrets via the secrets property, or fetch a specific one by ID.

# List all secrets
for secret in unlocked.secrets:
    print(secret.name, secret.secret_type, secret.payload)

# Get a specific secret by ID
secret = unlocked.get_secret(secret_id)
print(secret.payload)

// List all secrets
for (const secret of unlocked.secrets) {
  console.log(secret.name, secret.secretType, secret.payload);
}

// Get a specific secret by ID
const secret = await unlocked.getSecret(secretId);
console.log(secret.payload);

# List all secrets (metadata only)
inkbox vault secrets

# Filter by type
inkbox vault secrets --type api_key

# Get and decrypt a specific secret
inkbox vault get secret_abc123

Updating and deleting secrets

Update a secret’s name, description, or payload. Delete secrets when they’re no longer needed.

from inkbox.vault import APIKeyPayload

# Update a secret's payload
unlocked.update_secret(
    secret_id,
    payload=APIKeyPayload(
        api_key="replacement-api-key",
        endpoint="https://api.example.com/v1",
    ),
)

# Delete a secret
unlocked.delete_secret(secret_id)

// Update a secret's payload
await unlocked.updateSecret(secretId, {
  payload: {
      apiKey: "replacement-api-key",
      endpoint: "https://api.example.com/v1",
  },
});

// Delete a secret
await unlocked.deleteSecret(secretId);

# Update is available via the SDK or API

# Delete a secret
inkbox vault delete secret_abc123

Storing logins with TOTP

Login secrets can include a TOTP configuration for two-factor authentication. Use parse_totp_uri to parse a standard otpauth:// URI into a TOTP config, then attach it to the login payload.

from inkbox.vault.totp import parse_totp_uri
from inkbox.vault.types import LoginPayload

totp_uri = "otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"

unlocked.create_secret(
    name="Example",
    payload=LoginPayload(
        username="user@example.com",
        password="s3cret!",
        url="https://example.com/login",
        totp=parse_totp_uri(totp_uri),
    ),
)

import { parseTotpUri } from "@inkbox/sdk";

const totpUri = "otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example";

await unlocked.createSecret({
  name: "Example",
  payload: {
      username: "user@example.com",
      password: "s3cret!",
      url: "https://example.com/login",
      totp: parseTotpUri(totpUri),
  },
});

inkbox vault create \
--name "Example" \
--type login \
--username "user@example.com" \
--password "s3cret!" \
--url "https://example.com/login" \
--totp-uri "otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"

You can also build a TOTP config manually instead of parsing a URI:

from inkbox.vault.totp import TOTPConfig

totp = TOTPConfig(
    secret="JBSWY3DPEHPK3PXP",
    algorithm="sha1",  # sha1, sha256, or sha512
    digits=6,          # 6 or 8
    period=30,         # 30 or 60 seconds
    issuer="Example",
    account_name="user@example.com",
)

import type { TOTPConfig } from "@inkbox/sdk";

const totp: TOTPConfig = {
  secret: "JBSWY3DPEHPK3PXP",
  algorithm: "sha1",  // sha1, sha256, or sha512
  digits: 6,          // 6 or 8
  period: 30,         // 30 or 60 seconds
  issuer: "Example",
  accountName: "user@example.com",
};

# The CLI accepts TOTP via the otpauth:// URI format with --totp-uri
# Manual TOTP config building is available via the SDK

Generating TOTP codes

Once a login secret has a TOTP config, generate the current one-time code with get_totp_code. The code, expiry window, and seconds remaining are returned.

code = unlocked.get_totp_code(secret_id)
print(code.code)               # e.g. "482901"
print(code.seconds_remaining)  # seconds until this code expires

const code = await unlocked.getTotpCode(secretId);
console.log(code.code);              // e.g. "482901"
console.log(code.secondsRemaining);  // seconds until this code expires

# Generate a TOTP code for a secret scoped to an identity
inkbox identity totp-code my-agent secret_abc123

The returned TOTPCode includes:

Field	Type	Description
`code`	string	The current OTP code (e.g. `"482901"`)
`period_start`	number	Unix timestamp when this code became valid
`period_end`	number	Unix timestamp when this code expires
`seconds_remaining`	number	Seconds left until expiry

You can also generate codes directly from a TOTP config without storing it in the vault:

from inkbox.vault.totp import generate_totp, parse_totp_uri

config = parse_totp_uri("otpauth://totp/Test?secret=JBSWY3DPEHPK3PXP")
code = generate_totp(config)
print(code.code)

import { generateTotp, parseTotpUri } from "@inkbox/sdk";

const config = parseTotpUri("otpauth://totp/Test?secret=JBSWY3DPEHPK3PXP");
const code = generateTotp(config);
console.log(code.code);

# Standalone TOTP generation is available via the SDK

Identity access control

Grant specific agent identities access to individual secrets. This lets you control which agents can use which credentials.

# Grant an identity access to a secret
inkbox.vault.grant_access(secret_id, identity_id)

# List access rules for a secret
rules = inkbox.vault.list_access_rules(secret_id)
for rule in rules:
    print(rule.identity_id)

# Revoke access
inkbox.vault.revoke_access(secret_id, identity_id)

// Grant an identity access to a secret
await inkbox.vault.grantAccess(secretId, identityId);

// List access rules for a secret
const rules = await inkbox.vault.listAccessRules(secretId);
for (const rule of rules) {
  console.log(rule.identityId);
}

// Revoke access
await inkbox.vault.revokeAccess(secretId, identityId);

# Revoke an identity's access to a secret
inkbox identity revoke-access my-agent secret_abc123

# Grant access and list rules are available via the SDK or API

Vault metadata

Check the vault’s ID and counts without unlocking it. info() returns None in Python or null in TypeScript if your organization has not initialized a vault.

info = inkbox.vault.info()
if info is not None:
    print(info.id)
    print(info.secret_count)  # number of stored secrets
    print(info.key_count)     # number of primary vault keys

const info = await inkbox.vault.info();
if (info !== null) {
  console.log(info.id);
  console.log(info.secretCount);  // number of stored secrets
  console.log(info.keyCount);     // number of primary vault keys
}

# Show vault info
inkbox vault info

# List vault keys
inkbox vault keys

Managing vault keys

Rotate the primary vault key or revoke an existing key by auth hash. Rotating the primary key keeps the same organization encryption key and re-wraps it under the new primary vault key.

# Rotate the primary vault key using the current key
key = inkbox.vault.update_key(
    "My-N3w-Vault-Key!",
    current_vault_key=vault_key,
)
print(key.id)

# Or rotate using a recovery code
inkbox.vault.update_key(
    "My-N3w-Vault-Key!",
    recovery_code="ABCD-EFGH-JKLM-NPQR-STUV-WXYZ-2345-6789",
)

# Revoke a recovery key or other existing key by auth hash
inkbox.vault.delete_key("a1b2c3d4e5f6...")

// Rotate the primary vault key using the current key
const key = await inkbox.vault.updateKey({
newVaultKey: "My-N3w-Vault-Key!",
currentVaultKey: vaultKey,
});
console.log(key.id);

// Or rotate using a recovery code
await inkbox.vault.updateKey({
newVaultKey: "My-N3w-Vault-Key!",
recoveryCode: "ABCD-EFGH-JKLM-NPQR-STUV-WXYZ-2345-6789",
});

// Revoke a recovery key or other existing key by auth hash
await inkbox.vault.deleteKey("a1b2c3d4e5f6...");

# Rotate the primary vault key using the current key
inkbox vault update-key \
--new-vault-key "My-N3w-Vault-Key!" \
--current-vault-key "My-Str0ng-Vault-Key!"

# Or rotate using a recovery code
inkbox vault update-key \
--new-vault-key "My-N3w-Vault-Key!" \
--recovery-code "ABCD-EFGH-JKLM-NPQR-STUV-WXYZ-2345-6789"

# Revoke a key by auth hash
inkbox vault delete-key a1b2c3d4e5f6...

Deleting the vault

Delete the vault and all its keys and secrets from the Inkbox Console. This is destructive and permanently removes access to all stored secrets. After deletion, the organization can initialize a new vault. Vault deletion is not available through the SDK or CLI. Use the Inkbox Console instead. After deletion, you can initialize a new vault.

Close the Python client

After you finish using the vault, close the Python client to release its connections:

Python

inkbox.close()

Get started

Capabilities

API keys

MCP

Webhooks

Signing keys

Skills

Integrations

How it works

Secret types

Open the SDK client

Initializing the vault

Unlocking the vault

Creating secrets

Reading secrets

Updating and deleting secrets

Storing logins with TOTP

Generating TOTP codes

Identity access control

Vault metadata

Managing vault keys

Deleting the vault

Close the Python client

​How it works

​Secret types

​Open the SDK client

​Initializing the vault

​Unlocking the vault

​Creating secrets

​Reading secrets

​Updating and deleting secrets

​Storing logins with TOTP

​Generating TOTP codes

​Identity access control

​Vault metadata

​Managing vault keys

​Deleting the vault

​Close the Python client

How it works

Secret types

Open the SDK client

Initializing the vault

Unlocking the vault

Creating secrets

Reading secrets

Updating and deleting secrets

Storing logins with TOTP

Generating TOTP codes

Identity access control

Vault metadata

Managing vault keys

Deleting the vault

Close the Python client