Secrets Storage

View Integrations in the API reference

Integration configs can include sensitive values (API keys, tokens, passwords). OpenApp stores these in AWS Secrets Manager instead of the database.

Which fields are stored in Secrets Manager

Each integration provider declares a secrets schema. Fields that belong to this schema are stored in Secrets Manager; all other config fields are stored in the database.

Provider	Secret fields
Shelly Cloud	auth_key, server_uri (required); org_key (optional, LoRa mesh only)
Home Assistant	token
PalGate Cloud	session_token_hex
go2rtc	nvr_username, nvr_password
KNX, MQTT, Shelly Websocket, Tasmota, Virtual Access, Virtual Demo, Waveshare	None

Some providers keep credentials outside the secrets schema: MQTT and Waveshare broker passwords live in integration config, and Tasmota mqtt_password / web_password live in device metadata. Those fields are stored in the database, and every read response redacts them (the response lists which are set in credentials_set); they are returned only by the provisioning endpoints that require devices:update or integrations:update.

Secrets are never stored in the database

• Non-secret config (e.g. base_url, rate_limit_min_interval_ms) is stored in the database.
• Secret values are stored only in AWS Secrets Manager. The database never contains them.

API behavior

• Create: POST /integrations accepts two separate fields:
  • config: non-secret JSON object (stored in DB)
  • secrets: secret JSON object (stored in Secrets Manager)
• Update: PUT /integrations/{id} supports independent, tri-state patches for both:
  • config: omitted = unchanged, null = clear, object = replace
  • secrets: omitted = unchanged, null = clear (delete from Secrets Manager), object = replace
• Read: GET /integrations/{id} never returns secrets.
• Read secrets: GET /integrations/{id}/secrets returns the secrets JSON object. Requires integrations:read on the integration’s org and an X-Org header; deleted integrations return 404. Scoped API keys and agent credentials cannot call it (403). The route is not in the published OpenAPI document.
• List: List responses never include secrets.
• Soft delete: Secrets remain in Secrets Manager so the integration can be restored.
• Hard delete: The secret is overwritten with an empty object, then deleted from Secrets Manager, before the DB record is purged.