A map of which secrets exist in your workspace, how each one is stored, and what changing, rotating, and revoking mean for each one — because they don't mean the same thing.
There's no single principle for "all credentials"
This page once stated that, for every credential, the raw value appears once, that losing it means generating another one, and that the old one is rejected immediately. That's only true for part of family 1 below — the issued keys. A credential that the product needs to use at your data source is recoverable by nature, and "rejecting the old one" depends on someone revoking it there, not here.
The families#
| Family | What the system does with the secret | Examples |
|---|---|---|
| 1. Verifiers | It only checks a value you present. The stored value is a hash; not even we can get back to the original. | 1a. data API key and service principal (keys issued by the product) · 1b. sign-in password |
| 2. Recoverable source credentials | It needs to use the value to authenticate to your database/API. The value is encrypted and read back at run time. | password/token/key of a data connection |
| 3. Signing and computation secrets | It needs the value to sign or compute something of ours. Encrypted, recoverable, but it never goes back out to you afterward. | embed secret, MFA TOTP seed, workspace service account key |
The difference isn't cosmetic: it decides what happens when you change the value.
The sign-in password is
not an issued key Family 1 groups two things by the way they're stored (both are hashes), but they behave differently when it comes to changing them, and treating them together is what produced the previous page. An issued key is born in the product, appears once, is revocable, and stops working the instant you revoke it. A sign-in password identifies a person, isn't revocable piece by piece, and — with today's session design — changing it doesn't end sessions that are already open. That's why the two halves are separated below.
Family 1a — Keys ISSUED by the product (data API and service principal)#
How it's stored. The data API key (ing_live_…) and the service principal
(sp_live_…) become a SHA-256 of the raw value, plus a 16-character
prefix stored in the clear only so you can identify the key in the list.
Raw value. It appears only once, at creation. There's no way to show it again — the database doesn't have the original.
Lost it? Generate another one and revoke the previous one. There's no recovery.
Changing = rotating. Here the two words coincide: the credential is born and dies inside ingestia.io; no copy of it exists in another system.
Is the old one rejected immediately? Yes. Every request resolves the key
by looking up the database by hash and stops if there's a revokedAt. There's no cache of resolved
keys and no grace window — the read goes to the database on every call.
Scope. The service principal carries the role in the credential's own
envelope and falls back to viewer when the envelope is unreadable (fail-closed). An
ing_live_… token is never accepted as a service principal, and vice versa: the
prefix is checked before any lookup.
API key (data)
In Settings → API keys, generate a new key, update your integrations, and revoke the old one. From the moment of revocation, calls with the old key respond
401— no waiting.Service principal
Generate a new
sp_live_…with the appropriate role, point the IdP/integration to it, and revoke the previous one. Revoking an SP from another workspace is rejected (the check is by owner, not by id).
Family 1b — Sign-in password#
How it's stored. A salted scrypt hash, in the scrypt$N$sal$hash format. The
server only checks what you type; the original value isn't kept anywhere.
Where it's set. At account sign-up (email + password). It's the only point in the product that writes the sign-in password.
There's no self-service password change or reset
The implemented version has no "change my password" screen and no "forgot my password" flow. This page once stated that "each person changes their own" — that doesn't match the product and has been removed. Changing the password of an existing account is, today, a support case, like MFA recovery. People who sign in with Google or SSO don't have a local password: the change happens at the identity provider, not here.
Does the old one stop working right away? For authenticating, yes: sign-in checks the stored hash, so a replaced password doesn't open a new session. But sessions that are already open remain valid: the session is a signed token, stored in the browser of whoever signed in, and the server doesn't keep a list of sessions to revoke. So there's no "sign out of all devices". An open session ends when the person signs out or when the token expires.
What about the cache? There's no password cache. Within a single request, the session is resolved only once (per-request memoization), and none of this crosses requests. What survives the change is the token already issued — see the paragraph above — not a server cache.
Member invitations don't issue a password — they issue an activation link
When you register someone in Settings → Users, the product doesn't generate a temporary password. It issues a single-use activation token, with an expiration, stored as a hash; the person receives an activation link and sets their own password when accepting. The token is an invitation credential, not an access credential: it works once, to join the workspace, and then is no longer valid.
If the link expires or gets lost, the action is to resend the invitation (which issues a new token and invalidates the previous one). There's no "generate new password".
Family 2 — Credentials for your data sources#
This is the family where "rotating" is ambiguous, and where confusion is costly.
How it's stored. Two possibilities, per connection:
- encrypted in the database (AES-256-GCM) — today's default; or
- in the external credentials vault, with the database storing only a
reference. The reference points to a numbered version (never
latest).
Raw value. You type it, the product uses it, and the interface doesn't give the value back afterward. To change it, use Replace credential — there's no "see the current password". But note: not showing it again isn't the same as not being recoverable. Processing needs to authenticate to your database, so the value is decrypted on every run.
Changing the value here does NOT complete the rotation
The text the screen itself shows on every change: "Changing the value in the vault does NOT complete the rotation. The previous credential stays VALID at the source (database, provider, IAM) until it's invalidated THERE. Only mark the rotation as complete after revoking the old credential at the source — until then, consider it exposed."
That's why the connection has its own rotation status, with three values:
| Status | What it means |
|---|---|
| No rotation | The version in use is the one originally registered. |
| Value changed in the vault | There's a new version, validated and promoted — but nobody has confirmed that the previous credential was invalidated at the source. The rotation isn't over. |
| Completed at the source | Someone with access to the source confirmed the revocation there. Only here is the rotation finished. |
The change cycle, in the order it happens. Each step only runs if the previous one succeeded, and the screen's report shows each one:
- ensure the secret in the vault (idempotent);
- create the new version;
- validate — read the version back and check that the written fields are exactly the expected ones. Without this, promoting would be a leap of faith;
- promote — the reference now points to the new version;
- invalidate the connection's cache;
- retire the previous version — disabled, not destroyed (window for rollback and forensics).
If validation (step 3) fails, nothing is promoted: the new version is disabled and the previous credential stays in use. Step 6 is the only "best effort" one: failing to retire doesn't undo a new credential that's already valid — and the report says that the old version stayed enabled in the vault.
Cache. The resolved value stays in process memory, valid for 5 minutes, and the cache key includes tenant + connection + secret + version. Practical consequences:
- promoting a new version changes the key, so the old value isn't served by mistake;
- rotation and revocation invalidate the cache immediately in the process that ran the operation;
- in other processes (the pipeline runner runs somewhere else), the ceiling is the 5-minute validity;
- the secret never goes to an external cache (shared cache, disk) or to a key without the version.
Processes in progress. Resolution happens at the start of the run. A run that has already started finishes with the value it resolved; it isn't interrupted by a change made in the middle. The next run resolves again and already uses the new credential — or fails, if you revoked it.
Revocation. Revoking marks the reference as revoked and disables the version in the vault. After that, every resolution fails closed. And, deliberately, revocation doesn't:
- fall back to the credential encrypted in the database (that would make the revocation look applied without being so);
- reopen the previous version;
- delete the version (destroying is irreversible and would prevent forensics).
No silent fallback. When a vault reference exists, the vault is the only source. Vault unavailable or IAM denied stop the run with an actionable message and a stable code — they never resolve to a global secret, a same-name secret, or another tenant's. A reference from another workspace or another connection is rejected before any network call.
Family 3 — Signing and computation secrets#
These are ours, not your source's. The product needs the value to sign a token or compute a code — and that's why they're encrypted (AES-256-GCM), not hashed.
Dashboard embed secret
- Stored encrypted. The pair is
keyId(public, travels in the token) +secret. - Rotating changes both at once. Every token already issued stops working
immediately, because verification compares the token's
keyIdwith the currentkeyIdbefore looking at the signature. - Update the secret on your server before rotating, or the embedded dashboard stops along with it.
MFA seed (TOTP)
- Stored encrypted; the verifier recalculates the six-digit codes from it.
- Inventoried limitation: the reader tolerates a legacy plain-text seed (records prior to encryption). If decryption fails, the stored value is used as is. Old records may therefore not be encrypted yet.
- There are no single-use recovery codes in the product today. This page once listed them; there's no corresponding implementation. Losing the MFA device is a support case, not a self-service one — see Support.
Workspace service account key
- Used to access the processing's cloud resources; stored encrypted or in the managed vault.
- Rotating invalidates the current key: tools that use the old key stop. Download and distribute the new one before rotating.
What is encryption and what is a verifier (checklist table)#
This table describes the current implementation, not an intention.
| Credential | How it's stored | Why |
|---|---|---|
| Sign-in password | verifier (salted scrypt) | the server only checks what you type. Set at sign-up; no change/reset screen today |
| API key (data) | verifier (SHA-256) + visible prefix | you present the key; we only check it. The prefix identifies the key in the list |
| Service principal | verifier (SHA-256) + prefix + role in the envelope | same, with the role traveling along (fail-closed → viewer) |
| Your source's credential | encrypted (AES-256-GCM) in the database, or a reference to a version in the credentials vault | processing needs to authenticate to your database/API. A hash wouldn't authenticate anywhere |
| Embed secret | encrypted (AES-256-GCM) | it's the key that signs the embedded dashboard's tokens |
| MFA seed (TOTP) | encrypted (AES-256-GCM); reading tolerates legacy plain text | the verifier recalculates the codes from it |
| Service account key | encrypted, or in a managed vault when available | it's used to access the processing's cloud resources |
The encryption key comes from a dedicated server environment variable; in production, its absence fails closed instead of falling back to a development value.
Quick inventory#
| Credential | Prefix/form | Creates/revokes | Scope | Where it's documented |
|---|---|---|---|---|
| API key (data) | ing_live_… | owner only | workspace (reads all published marts) | API authentication |
| Service principal | sp_live_… | admin/owner | the SP's workspace/org, with a role in the envelope | SSO and SCIM |
| Embed secret | public keyId + secret | workspace actions | one dashboard per signed token | Embed SDK |
| Source credential | per connector (password/token/OAuth/key) | admin/owner (source.manage) | one connection | Connectors |
| Sign-in/MFA | password (verifier) + TOTP seed (encrypted) | password: only at sign-up (no self-service change) · MFA: each person turns on their own | their own identity | Authentication and MFA |
What applies to all of them#
Three things — and only three — apply to every family:
- Workspace scope. Every credential resolves only the workspace/org that issued it. None crosses customers, and the owner check happens before any read.
- Least privilege. A
viewerservice principal is denied (403) on actions above its role — see RBAC. - No secrets in logs, errors, audit, exports, or DAGs. Values don't appear in error messages or log lines; the pipeline definition stores the connection's reference, never the credential.
When to rotate#
- Suspected leak (secret in a log, shared URL, screenshot): treat it as a Critical incident (Support). For family 2, remember that the step that ends the risk is revocation at the source.
- Departure of a person with access to the secret.
- Periodic hygiene of integration credentials.
Limits#
- Data key = workspace level (no per-member scoping). A per-member key with RLS is on the
Roadmap. - The embed origin allowlist is instance-wide today (per-workspace =
Roadmap) — see Embed. - A single external vault supported — the product's own. Moving the credentials to a vault of your own is the Credential Management add-on, and it isn't included in the plan.
- No MFA recovery codes (see family 3).
- Refresh token rotation for some OAuth connectors (Bling, Conta Azul, HubSpot) isn't persisted — that's why setting up these connectors is rejected today. See Connectors.
Common errors and how to fix them#
| Symptom | Likely cause | What to do |
|---|---|---|
Integration stopped with 401 | key revoked/rotated | update the integration with the new key |
| Every embed token stopped | the embed secret was rotated (changes keyId and secret) | update the secret on your server |
| The secret "disappeared" after creation | family 1a: the issued key's raw value only appears once | generate another key and revoke the previous one |
| I changed the password and the source still accepts the old one | expected behavior: changing it here doesn't revoke it there | revoke it at the source and mark the rotation as complete |
| Run failed with "credential revoked" | the reference is revoked in the vault | register a new credential; there's no going back to the old database value |
| Run failed with "vault unavailable" | credentials vault down or access denied | failing closed on purpose; nothing was resolved by approximation |
| The run in progress used the old credential | the secret is resolved at the start of the run | expected; the next run uses the new one |
| Source failing after a while | OAuth refresh token not persisted | reconnect the source; these connectors are blocked today |
Example#
A Comércio Aurora (fictional) script had its ing_live_… key leaked in a
log. Maria (owner) generates another key, updates the integration server, and
revokes the old one — every call with the leaked key responds 401 immediately.
If what had leaked were the source database password, the playbook would be different: changing the value on the connection settles which password ingestia.io uses, but whoever copied the old password keeps getting into the database until someone revokes it in the database. Only then is the rotation marked as completed at the source.
Expected result#
- Family 1a: the new key works and the old one responds
401immediately. - Family 1b: a replaced password doesn't open a new session — but the session that was already open continues until sign-out or expiration; there's no session revocation.
- Family 2: the new version is the one the product uses; the source is only safe after revocation there, and the connection records that status.
- Family 3: the new secret signs/computes, and whatever depended on the old one stops working immediately.
- No credential resolves data from another workspace.
Related#
Last reviewed: 2026-09-17. The families, the change cycle, the cache, the run-time behavior, and the limits above were checked against the product's code, not against a general principle.