# Vault, settings and events (/docs/apis/vault-and-events)

An addon may need to remember preferences, store a private value or react when the timer starts. This guide explains where to keep each kind of information and how to receive these notifications.

The application manages credentials used to connect external accounts through `core.connections`. Use `host.vault` for other private addon values and for reading saved settings; do not create another store for the same account tokens.

## Explicit scopes [#explicit-scopes]

- `{ kind: 'addon' }`
- `{ kind: 'workspace', workspaceId }`
- `{ kind: 'connection', workspaceId, connectionInstanceId }`
- `{ kind: 'capability', workspaceId, connectionInstanceId, capabilityId }`

`get(scope, key)`, `set(scope, key, value)` and `delete(scope, key)` return `Either`. A missing private string is `null`. Access to connection/capability scopes is validated by the host. The capability-scoped vault address is not a per-capability manifest descriptor. UI navigation never supplies an implicit target.

## Declarative settings [#declarative-settings]

Register schemas through `contributions.settings.register(schema, { onApply })`. Non-secret settings have a revisioned snapshot; read it with `host.vault.getSettings(scope)`. `onApply` receives scope, revision, values, events and `track` for cleanup. Do not read normal settings from an arbitrary private vault key.

## Runtime and cleanup [#runtime-and-cleanup]

Register providers and return from `activate`; waiting for ready there can block bootstrap. `core.runtime.onStateChanged` immediately reports the current state, then transitions among `starting`, `ready`, `restarting`, `closed`. Readiness does not mean remote pull has completed.

The host cleans up contributions and tracked listeners on deactivation or failed activation. Close owned sockets, clients and jobs yourself. Switching workspace does not deactivate the addon.

## Guaranteed events [#guaranteed-events]

`timer:start`, `timer:pause`, `timer:resume`, `timer:stop`, `timer:update`, `workspace:changed`.

These are transient projections without replay or guaranteed per-second ticks. Idle and arbitrary time-entry events are not guaranteed SDK APIs. Use `context.core.timer` and `context.core.timeEntries` for reads and writes with explicit workspace and operation IDs. For connection authentication, see [authentication](/docs/capabilities/auth).