Manage secrets

A secret is a stored credential — an API key, an OAuth connection, a database login, or a client-credentials pair — owned by a feature. Workflows, connections, and MCP servers use secrets to reach external systems. The defining rule: a secret’s sensitive values are never displayed anywhere in the product — not to you, not to other members, and not to the agent.

Create a secret

There is no “Add secret” form anywhere in Ronja. Like most resources, secrets are created in conversation:

Open an exploration and tell Ronja what you want to connect — “connect our Postgres” or “I have an API key for our billing tool”.
The conversation pauses and a secure credentials card opens just above the message box. Fill it in. Sensitive fields show a 🔒 sensitive badge and a password-style input; values Ronja pre-filled from the conversation carry a “filled by agent — verify” badge (sensitive values are never pre-filled).
Click Save credentials and Ronja resumes the same conversation right where she paused. Or click Skip for now to defer entering them — the secret stays pending and Ronja carries on without it. You can finish it later yourself: open the secret’s page, which shows you the short form described below.

A script, or an AI agent working from your terminal with ronja secret create --in-browser (see Use the Ronja CLI), can also start a secret without its value. It then sends you to the secret’s page, which shows only a short form titled Connect and the secret’s name. The first line says where Ronja will use the value, naming the company that owns each address, such as “Ronja will use this to connect to granola.ai.” An address that is not what it looks like is flagged in plain words underneath: one with unusual characters that may imitate another site, one that is not a web address Ronja can use, or a wildcard that covers every address ending in a domain. Fill in the fields and click Save; fields marked (optional) can be left blank, and the eye button shows a value you have just typed. The last line says when the secret was requested and by whom: by you, by Ronja’s agent in a chat, through your access token, by name (the CLI’s is named after your computer), or by an app or automation. If you were not expecting the request, close the page without entering anything. After you save, the page says the secret is connected and you can close the tab. Secret settings under the form opens the secret’s full page, and Back returns to the form. The value never passes through the script or agent that asked for it, but whoever can edit the secret or the feature’s workflows can still use it and change where it goes. The form shows only to the secret’s owner, and only while the secret is waiting for its value.

For database logins, defaults appear beside the fields. Leave a field blank to use its default; optional SSH settings are under More settings. Ronja still checks the database’s required fields when you save.

For OAuth services Ronja shows a Sign in with {Provider} card in the chat instead — you approve access in a popup, and no credential passes through the chat at all.

Choose what a connection may do

Some services let you pick the connection’s permissions before you sign in. Where they do, the card shows a Permissions to request list above the sign-in button, with one checkbox per permission and a plain description of what it covers.

Everything the service offers starts ticked. Untick anything you do not want the connection to have, then sign in — the provider is asked for exactly the permissions left ticked, and nothing else.

Two things to know while you are choosing:

One permission is always on and cannot be unticked. Ronja needs it to tell your accounts apart — for Fortnox that is Company Information. It is locked rather than hidden, so you can see what it covers.
Some services cannot grant read-only access. Where every permission a service offers also allows changes, the card says so directly, for example “Every Fortnox permission also allows changes in Fortnox.” That is the provider’s limit, not Ronja’s.

If you are narrowing an existing connection rather than making a new one, the card warns you first: “Workflows, automations and agents that use this connection lose this permission too.” Removing a permission reaches everything already built on that connection, not just the conversation you are in.

Services that do not offer a choice show the sign-in button on its own, exactly as before. Today Fortnox is the only one that does; the rest request a fixed set.

See and change what a connection holds

Once connected, expand the card to see Permissions: followed by the list actually granted. This is what the provider gave, not what was asked for — if you declined something in the provider’s own consent screen, it shows here, and Ronja tells you rather than letting you discover it later through a failed request.

To change the permissions afterwards, click Re-authorize on the connected card. The picker reopens with the current permissions ticked, and signing in again replaces the grant with whatever you leave ticked. Widening works the same way: if Ronja needs a permission the connection does not have, she asks for it by name and pre-ticks it for you.

Find a secret

Each feature lists its secrets in the feature hub, and every secret has a detail page showing: a type chip (API Key, OAuth, Client Credentials, Public Endpoint, or database), Personal or Shared, Live or Archived, and a Configuration card with Type, Dialect (if set), Credentials (“Stored” / “Not set”), Allowed URLs — the only hosts the secret may be used against — and Agent-visible fields, the only fields the agent may reference by name.

What you will never find is a value. Saved fields render only as “● ● ● ● saved” length indicators; only non-sensitive fields such as host, port, and username appear in plain text.

Review integrations across the organization

Admins can open Integrations in the admin sidebar to see credentials grouped by the external system they connect to. Each group shows its health and credentials, with their owner and Private or Organization scope. Check details appear where available. Click a credential name to open its detail page. The page’s header names the feature the credential lives in, as a link to that feature. For a colleague’s private credential, that is how you reach their feature, for example to share it with the organization. Integrations lists colleagues’ private credentials for admins. Ronja’s chat and AI assistants connected to Ronja find what a member would, plus the feature you open the chat in and anything you link them to. No screen, list or export ever shows a secret’s value.

A managed database’s group is titled with the database’s name, and its logins at different levels (for example its read and write logins) are grouped together but are not duplicates: each of those rows names its level, such as read login.

Credentials whose external identity has not been established appear separately under Unidentified. That can mean a check is pending or could not establish the identity; it does not by itself mean the credential is unusable. Health explanations describe which cases need attention.

Health and re-authorization

The Health & identity card on the detail page (first in the main column, or just below Enter the value when you open Secret settings on a secret of yours that is waiting for its value) shows one state for the secret: Healthy, Not checked, Check failed, Duplicate credentials, Connected elsewhere, Credentials conflict, or Reauth required. All but the last are advisory — a working credential is never blocked by them — and Recheck now runs the check again where one applies. On a secret that logs in the button reads Refresh status: it shows the result of the last login and never logs in.

Reauth required is the state that blocks: the stored sign-in could not be renewed, so Ronja refuses to use the secret until it is restored. Reconnect appears only for services Ronja signs you in to. For a secret that uses your own OAuth app, run its sign-in again with Rotate tokens in the Actions rail, or ask Ronja in chat to save a fresh token — its owner or an Admin can do that. Rotate tokens is not offered on a connection Ronja signs you in to, on a mailbox’s connection, which you reconnect with Reconnect on the Mailboxes page, on a secret carrying the client ID of one of Ronja’s own apps (below), or on a SharePoint key.

A secret that carries the client ID of one of Ronja’s own apps without being one of Ronja’s connections can no longer renew or sign in, and its health check says so. Connect it with your own app’s credentials: ask Ronja in chat to update the same secret with your app’s client ID and secret.

SharePoint keys

A SharePoint key is the secret an Admin makes with Create SharePoint key on a SharePoint connection Ronja support has approved; Workflows use it to read files from the SharePoint sites your Microsoft organization shared with Ronja. Nobody can write or edit its credentials, and it has no Rotate tokens or Reconnect: Ronja renews its access by itself. When that fails, its Health & identity card shows Check failed with the reason, such as “This SharePoint key’s Microsoft organization is not connected to this Ronja organization.” or Microsoft’s own message, and the key recovers by itself once the cause is fixed. See Connect a data source for where the button is.

Secrets that log in

Some business systems, Monitor G5 among them, have no API key. You log in with a username and password, get a session back, and every request carries that session until the system refuses it. Monitor also allows one live session per user, and every new login ends the others, so two workflows that each logged in would keep logging each other out.

For a system like that, ask Ronja to connect it (“connect our Monitor ERP”). She stores the username and password in one secret, with the password marked sensitive, and writes a small workflow called the secret’s login workflow, which does nothing but log in. From then on:

Ronja logs in once for everyone. However many workflows, chats and apps need the system at the same moment, Ronja runs the login workflow once and gives them all the same session. When a session is refused, Ronja first checks whether a newer one already exists, and logs in again only when it does not.
Chats and apps get a new session by themselves; a workflow asks for one. When the system refuses a chat’s or an app’s request with 401, Ronja logs in again and sends the request once more with the new session. In an app’s server function the refused call itself fails, and the next call gets the new session. A workflow decides for itself when its session is gone: its code calls tools.renewSecret with the refused session, gets the new one back and sends the request again.
The password reaches only the login workflow. Every other workflow and chat that uses the secret gets the session and the fields that are not marked sensitive, such as a company number. A workflow that still reads the password stops with an error naming the login workflow. When Ronja attaches a login workflow she is told which workflows still read the password; they fail from then on until she changes them to use the session.
Nobody runs the login workflow by hand. Running it is refused with “this workflow is the login for secret …”. Its run history records only whether each login worked, never the session or what the login printed.
A login workflow can’t be deleted or archived while its secret logs in with it: its removal lists the secret as “logs in with this workflow”. To retire it, ask Ronja to attach a different login workflow to the secret, or delete the secret.
Saving a new password logs in straight away, so Ronja can tell you in the chat whether the password works.
A failed login waits before trying again: 30 seconds at first, doubling up to 15 minutes, so a wrong password is not retried in a tight loop, which makes a lockout at the vendor less likely. Saving a new password tries again straight away.
A system that refuses every new session is not logged in to again and again. When the system has refused three sessions within an hour of each other, each within two minutes of the login that got it, Ronja waits before logging in again, in the same way, and the secret’s health says it “keeps refusing new sessions; check the user’s permissions”. The user Ronja logs in as usually lacks a permission the workflows or apps need. Pressing Log in now, or saving the secret with a changed username or password, ends the wait.

If another program logs in to Monitor as the same user, Ronja’s session ends and the next request is refused. In chats and apps Ronja does not fight it for the session: that refusal is not answered with a new login. In a chat, Ronja’s answer says so; an app gets the system’s own refusal. A workflow that asks for a new session on that refusal does log in again, and so ends the other program’s session. A workflow run does not replace a session it got this way less than 15 minutes ago, and when runs keep refusing sessions that other runs got less than 15 minutes ago, Ronja waits before logging in again and emails the admins, as for a system that refuses every new session. Pressing Log in now ends both the wait and the 15-minute limit. Give Ronja a user of its own in the system.

The detail page of a secret that logs in has a Login section, below Health & identity:

Workflow — the login workflow, linked to its page.
Status — how the last login went: Logged in, Not logged in yet, Last login failed, Logging in, No session; Ronja logs in on next use once the session has ended or a save or an archive dropped it, or Could not be read when Ronja could not look up the last login just then.
Last login — when Ronja last logged in.
Last login run — View run opens the run of that login, which records whether it worked, never the session.
Session ends — when the session runs out, Until refused for a system like Monitor whose sessions last until it refuses them, or No session when none is stored.

Log in now logs the secret in straight away, even when a session is stored, and ends the wait after a failed login. It is there for anyone who may edit the secret: its owner, the owner of the private feature it is in, an Admin, or a maintainer of its feature. While it runs the button reads Logging in…. Its answer appears under the button: Logged in, or The login failed with the error. If you may also archive or delete the login workflow, you see the full error and whatever the workflow printed, so you can see why; anyone else sees Ronja’s one-line reason, since that output can show what the workflow read, the password included. That output is shown only to you, only this once: Ronja never stores it. A login that takes longer than 45 seconds finishes in the background, and the section says so. Pressing it again within 30 seconds of a login answers with that login’s session instead of logging in again. On a system like Monitor every login ends the user’s other sessions, so press it after a failed login or a change, not just to check: Status already says how the last login went.

When a secret keeps failing

When a secret’s login has failed three times in a row, its system has refused three new sessions within an hour, or a connection’s sign-in can no longer be renewed, a Secret needs attention notification goes out once, and at most once a day for the same secret, saying what to do: save the password again, check the user’s permissions, save a new client secret, or sign in again. A mailbox’s connection is not reported here; you reconnect it with Reconnect on the Mailboxes page. This one is on by default: your admins are emailed unless someone chooses different recipients, or turns it off, in the Connections & bridges group on Notification routing. A secret in a private feature is not named in the message; it says “A secret in a private feature” and links to the secret.

Update or rotate credentials

Ask Ronja in chat to update the secret. The credentials card opens above the message box with saved indicators on stored fields.
Type new values only into the fields you want to change — “Leave a field blank to keep its existing value.”
Click Save credentials.

When an OAuth secret’s authorization expires, the chat card shows “{Service} authorization expired” — click Re-authorize with {Provider} to run the consent popup again. For an OAuth secret that uses your own OAuth app, ask Ronja to update the secret and save a fresh token on the same credentials card: saving restores an expired secret whose sign-in does not renew itself. If the secret comes back needing re-authorization the next time it is used, its stored sign-in cannot be renewed at all — run the service’s own sign-in again with Rotate tokens on the secret’s detail page.

Scope: Personal vs Shared

A secret has no scope of its own — it inherits the scope of the feature that owns it. In a private feature it is Personal; in an organization-scoped feature it is Shared. To share a secret, you promote its feature as a bundle — see Share and promote.

Archive or delete

Archive (on the detail page) hides the secret from the agent: Ronja no longer finds or uses it in new work. Reverse it any time with Unarchive.