> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookfish.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Store API keys

> Encrypt, retrieve, and rotate API keys with the Hookfish SDK.

Hookfish stores API keys and other non-OAuth credentials in its encrypted
secret vault. Your application refers to each key by a stable resource path.

## Store an API key

```ts theme={null}
import { Hookfish } from '@hookfish/sdk'

if (!process.env.HOOKFISH_API_KEY) throw new Error('HOOKFISH_API_KEY is required')

const hookfish = new Hookfish({
  apiKey: process.env.HOOKFISH_API_KEY,
  baseUrl: 'http://127.0.0.1:8787/api',
})

await hookfish.secrets.put('acme/openai/api-key', 'sk-example')
```

Hookfish encrypts the value with `OAUTH_ENCRYPTION_KEY` before writing it to the
database.

## Use the API key

Retrieve secrets only in trusted server code:

```ts theme={null}
const { value: apiKey } = await hookfish.secrets.get(
  'acme/openai/api-key',
)
```

Pass `apiKey` to the provider's server-side SDK. Hookfish marks decrypted
responses as `no-store`; do not return the value to browser code or write it to
logs.

## List and delete API keys

Listing returns paths and timestamps without decrypting values:

```ts theme={null}
const { secrets } = await hookfish.secrets.list({
  path_prefix: 'acme',
})

await hookfish.secrets.delete('acme/openai/api-key')
```

Prefix matching respects path-segment boundaries. A prefix of `acme/tools`
does not match `acme/toolsmith`. Scoped broker tokens can access only paths
covered by their resource scopes.

<Warning>
  Keep vault operations in authenticated server routes. Paths below
  `__hookfish/` are reserved for Hookfish's internal credentials.
</Warning>