Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-09-17

Credentials and rotation

The workspace's secret families — issued keys, sign-in password, recoverable source credentials, and signing secrets — and what changing, rotating, and revoking means for each one.

On this page (17)

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#

FamilyWhat the system does with the secretExamples
1. VerifiersIt 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 credentialsIt 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 secretsIt 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.

  1. 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.

  2. 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:

StatusWhat it means
No rotationThe version in use is the one originally registered.
Value changed in the vaultThere'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 sourceSomeone 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:

  1. ensure the secret in the vault (idempotent);
  2. create the new version;
  3. 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;
  4. promote — the reference now points to the new version;
  5. invalidate the connection's cache;
  6. 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 keyId with the current keyId before 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.

CredentialHow it's storedWhy
Sign-in passwordverifier (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 prefixyou present the key; we only check it. The prefix identifies the key in the list
Service principalverifier (SHA-256) + prefix + role in the envelopesame, with the role traveling along (fail-closed → viewer)
Your source's credentialencrypted (AES-256-GCM) in the database, or a reference to a version in the credentials vaultprocessing needs to authenticate to your database/API. A hash wouldn't authenticate anywhere
Embed secretencrypted (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 textthe verifier recalculates the codes from it
Service account keyencrypted, or in a managed vault when availableit'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#

CredentialPrefix/formCreates/revokesScopeWhere it's documented
API key (data)ing_live_…owner onlyworkspace (reads all published marts)API authentication
Service principalsp_live_…admin/ownerthe SP's workspace/org, with a role in the envelopeSSO and SCIM
Embed secretpublic keyId + secretworkspace actionsone dashboard per signed tokenEmbed SDK
Source credentialper connector (password/token/OAuth/key)admin/owner (source.manage)one connectionConnectors
Sign-in/MFApassword (verifier) + TOTP seed (encrypted)password: only at sign-up (no self-service change) · MFA: each person turns on their owntheir own identityAuthentication 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 viewer service 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#

SymptomLikely causeWhat to do
Integration stopped with 401key revoked/rotatedupdate the integration with the new key
Every embed token stoppedthe embed secret was rotated (changes keyId and secret)update the secret on your server
The secret "disappeared" after creationfamily 1a: the issued key's raw value only appears oncegenerate another key and revoke the previous one
I changed the password and the source still accepts the old oneexpected behavior: changing it here doesn't revoke it thererevoke it at the source and mark the rotation as complete
Run failed with "credential revoked"the reference is revoked in the vaultregister a new credential; there's no going back to the old database value
Run failed with "vault unavailable"credentials vault down or access deniedfailing closed on purpose; nothing was resolved by approximation
The run in progress used the old credentialthe secret is resolved at the start of the runexpected; the next run uses the new one
Source failing after a whileOAuth refresh token not persistedreconnect 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 401 immediately.
  • 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.

Related links