Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt

Use this file to discover all available pages before exploring further.

Your agent will need to authenticate with external services — whether that’s a third-party API, an OAuth provider, or a database. The vault primitive gives your agent a private, encrypted store for secrets so credentials never live in your source code, environment variables, or log files. Only your agent can read what you put in.

​
How It Works

Every secret you store in the vault is encrypted at rest using AES-256 and is scoped exclusively to your agent’s identity. Secrets are decrypted in memory only at the moment your agent retrieves them — they are never surfaced in API responses, dashboard logs, or error traces.
Secrets stored in the vault are never echoed back in API responses or logs. If you lose a secret value, you must overwrite it with a new one — there is no plaintext retrieval path outside of your agent.

​
Storing and Retrieving Secrets

​
Set a secret

await agent.vault.set({
  key: 'OPENAI_KEY',
  value: 'sk-...',
});

​
Read a secret

const secret = await agent.vault.get({ key: 'OPENAI_KEY' });

// Use the value directly — it is never logged
await callExternalApi({ apiKey: secret.value });

​
List all secrets

const secrets = await agent.vault.list();

secrets.forEach((s) => {
  // Only key names and metadata are returned — never values
  console.log(s.key, s.updatedAt);
});

​
Delete a secret

await agent.vault.delete({ key: 'OPENAI_KEY' });

​
Use Cases

1

API key management

Store third-party API keys (Stripe, SendGrid, Twilio, etc.) in the vault and retrieve them at runtime. Your keys are never checked into version control or exposed in configuration files.
2

OAuth token management

Store access tokens and refresh tokens obtained during OAuth flows. The vault is the right place to persist tokens between agent sessions so your agent stays authenticated without re-prompting users.
3

Arbitrary secrets

Store database connection strings, webhook signing secrets, SSH keys, or any other sensitive value your agent needs to operate.

​
Best Practices

Keep credentials out of code

Never hardcode API keys or passwords in your agent’s source code. Write them to the vault once during setup and read them at runtime.

Rotate keys in the vault

When a third-party key is rotated, call agent.vault.set with the same key name and the new value. All subsequent reads will return the updated secret without any code changes.

Use descriptive key names

Name secrets after the service and permission scope — e.g. STRIPE_SECRET_KEY, GITHUB_READ_TOKEN. This makes vault.list() output self-documenting.

Avoid logging secret values

Even though the vault never logs values, make sure your own code doesn’t accidentally log the result of vault.get(). Treat the returned value as opaque.
Key rotation is non-destructive. Calling agent.vault.set with an existing key name overwrites the stored value in place — the key name, creation timestamp, and access history are preserved.

​
Available Parameters

​
key
string
required
A unique identifier for the secret within your agent’s vault. Conventionally uppercase and underscore-separated, e.g. STRIPE_SECRET_KEY.
​
value
string
The plaintext secret value to encrypt and store. Required for set, not used for get, list, or delete.