Env-secrets

An env-secret is an organization secret (a third-party API key, a certificate, a token) that Imaginne injects into a skill at execution time, as an environment variable. Secrets belong to the organization, are written once (write-only), and are never returned to the client. You manage them at /org/env-secrets. For the skill side (how a skill declares what it needs), see Env-secrets in skills.

How it works

The secret is only injected if the skill declares it in required_env. No carry-over between skills.

The core idea: the secret only enters the skill that declares it. At invocation, Imaginne resolves only the names declared by the skill (in required_env / env.secrets), filters them down to what it actually requires, and injects them into that skill's process. There's no carry-over between skills — each one receives only what it declared.

Name rule

An env-secret's name follows a fixed pattern and is unique per organization:

^[A-Z][A-Z0-9_]{0,127}$

That is: it starts with an uppercase letter, then uppercase letters, digits, and _, up to 128 characters. Valid examples: STRIPE_API_KEY, INTERNAL_CA_PEM, SAP_TOKEN.

Kinds

When creating one, choose the kind, which indicates the nature of the value:

Kind	For
string	Simple tokens and keys.
pem	Certificates/keys in PEM format (multiline).
json	Structured credentials in JSON.

Create, rotate, and delete

Action	Effect
Create	Name (per the rule), kind, and value. The value is write-only.
Rotate	Replaces the value (the new one is also write-only).
Delete	Removes the secret — with a lock (see below).

The value is write-only

Once saved, the value is not displayed. The Copy name action copies only the secret's name (to use in the skill's declaration), never the value. To change the content, use Rotate.

Deletion lock

Deleting a secret that is in use is refused:

• If the env-secret is referenced by some skill, Delete returns 422 and does not delete it.
• To force it anyway, repeat with force=true — assuming the skills that depend on it can go without the secret (and will fail with missing_required_env).

Manage skills

In Manage skills you attach and detach the secret from the organization's skills. Remember the injection rule:

Attaching isn't enough — the skill has to declare

Imaginne only injects the secret if the skill declares it in required_env (or env.secrets). Attaching it via the console makes the secret available; the declaration in the skill is what makes Imaginne deliver it at invocation. If a secret the skill requires is missing, execution fails with missing_required_env — configure/attach the corresponding env-secret.

See also

🧩Env-secrets in skills

How a skill declares what it needs to receive.

Open →🧠Skills (governance)

Manage a skill's secrets from the editor.

Open →🔐Credentials

The write-only credentials model and the deletion lock.

Open →