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

# Credential Vault: Secure Secrets for Your Agent

> Store encrypted secrets, OAuth tokens, and API keys in the Nonhumans Vault so your agent can authenticate with external services securely.

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.

<Warning>
  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.
</Warning>

***

## Storing and Retrieving Secrets

### Set a secret

<CodeGroup>
  ```typescript TypeScript theme={null}
  await agent.vault.set({
    key: 'OPENAI_KEY',
    value: 'sk-...',
  });
  ```

  ```python Python theme={null}
  await agent.vault.set(
      key="OPENAI_KEY",
      value="sk-...",
  )
  ```
</CodeGroup>

### Read a secret

<CodeGroup>
  ```typescript TypeScript theme={null}
  const secret = await agent.vault.get({ key: 'OPENAI_KEY' });

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

  ```python Python theme={null}
  secret = await agent.vault.get(key="OPENAI_KEY")

  # Use the value directly — it is never logged
  await call_external_api(api_key=secret.value)
  ```
</CodeGroup>

### List all secrets

<CodeGroup>
  ```typescript TypeScript theme={null}
  const secrets = await agent.vault.list();

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

  ```python Python theme={null}
  secrets = await agent.vault.list()

  for s in secrets:
      # Only key names and metadata are returned — never values
      print(s.key, s.updated_at)
  ```
</CodeGroup>

### Delete a secret

<CodeGroup>
  ```typescript TypeScript theme={null}
  await agent.vault.delete({ key: 'OPENAI_KEY' });
  ```

  ```python Python theme={null}
  await agent.vault.delete(key="OPENAI_KEY")
  ```
</CodeGroup>

***

## Use Cases

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Arbitrary secrets">
    Store database connection strings, webhook signing secrets, SSH keys, or any other sensitive value your agent needs to operate.
  </Step>
</Steps>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep credentials out of code" icon="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.
  </Card>

  <Card title="Rotate keys in the vault" icon="arrows-rotate">
    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.
  </Card>

  <Card title="Use descriptive key names" icon="tag">
    Name secrets after the service and permission scope — e.g. `STRIPE_SECRET_KEY`, `GITHUB_READ_TOKEN`. This makes `vault.list()` output self-documenting.
  </Card>

  <Card title="Avoid logging secret values" icon="eye-slash">
    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.
  </Card>
</CardGroup>

<Note>
  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.
</Note>

***

## Available Parameters

<ParamField body="key" type="string" required>
  A unique identifier for the secret within your agent's vault. Conventionally uppercase and underscore-separated, e.g. `STRIPE_SECRET_KEY`.
</ParamField>

<ParamField body="value" type="string">
  The plaintext secret value to encrypt and store. Required for `set`, not used for `get`, `list`, or `delete`.
</ParamField>