credentials Stable WINMACLNX

Store secrets in the OS-native credential store. Data is encrypted by the OS and tied to the logged-in user account — it never touches your database or files as plaintext and survives app updates.

Platform	Backend
Windows	Windows Credential Manager (DPAPI)
macOS	Keychain
Linux	Secret Service (GNOME Keyring / KWallet)

Capability

veloxkit.config.json

{
  "capabilities": ["credentials"]
}

Import

import { credentials } from 'veloxkit'

`credentials.set(key, value, opts?)`

Store a secret. Replaces any existing value for the same key.

await credentials.set('auth_token', userToken)
 
// Optional: custom service namespace (default: 'velox')
await credentials.set('api_key', apiKey, { service: 'my-app' })

Parameters

Param	Type	Description
`key`	`string`	Unique identifier for this secret
`value`	`string`	The secret value (any string; use `JSON.stringify` for objects)
`opts.service`	`string`	Service namespace (default: `'velox'`)

Returns Promise<void>

`credentials.get(key, opts?)`

Retrieve a stored secret.

const token = await credentials.get('auth_token')
if (token === null) {
  // no entry found — prompt user to log in
}

Returns Promise<string | null> — the stored value, or null if no entry exists.

`credentials.delete(key, opts?)`

Delete a secret. No-op if the key doesn't exist.

await credentials.delete('auth_token')

Returns Promise<void>

Examples

Auth token lifecycle

import { credentials } from 'veloxkit'
 
// On login:
async function onLogin(username: string, password: string) {
  const { token } = await fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify({ username, password }),
    headers: { 'Content-Type': 'application/json' },
  }).then(r => r.json())
 
  await credentials.set('session_token', token)
}
 
// On app start:
async function checkAuth() {
  const token = await credentials.get('session_token')
  if (token) {
    // Already logged in — use token for API calls
    return token
  }
  // No token — show login screen
  return null
}
 
// On logout:
async function onLogout() {
  await credentials.delete('session_token')
}

Storing JSON (API keys, config)

// Store a complex object
await credentials.set('llm_config', JSON.stringify({
  provider: 'openai',
  apiKey:   'sk-...',
  model:    'gpt-4o',
}))
 
// Retrieve and parse
const rawConfig = await credentials.get('llm_config')
const config = rawConfig ? JSON.parse(rawConfig) : null

Per-service namespacing

Use the service option when your app interacts with multiple third-party services:

await credentials.set('token', githubToken,  { service: 'github' })
await credentials.set('token', slackToken,   { service: 'slack' })
await credentials.set('token', notionToken,  { service: 'notion' })
 
// Each service has its own isolated namespace
const gh = await credentials.get('token', { service: 'github' })

Security notes

⚠️

Do not store secrets in:

The app's SQLite database (readable by anyone with filesystem access)
veloxkit.config.json or any file bundled with the app
Environment variables (visible in process listings)

Use credentials for runtime secrets (tokens, API keys the user provides). For build-time secrets that your backend needs, use a backend proxy instead of embedding them in the binary.

On Linux, Secret Service requires a running secrets daemon (GNOME Keyring or KWallet). On headless servers, this API may fail — handle rejections gracefully and fall back to a prompt.

window backend