C3 AI Documentation Home

Connect Secrets

A secret is an encrypted key/value pair, such as an API token, a webhook URL, or a database connection string, that you store once in C3 AI Agentix and an agent's session can then read at runtime. Connect one when an agent's skill or script needs a credential like these. Pasting the credential into a chat prompt or hardcoding it into a skill is both insecure, since it ends up in transcripts and source, and unmaintainable, since rotating the credential then means editing every place it was pasted.

A secret solves both problems: C3 AI Agentix injects its value into the session as an environment variable, so a skill can reference it by name, for example $GITHUB_TOKEN, and the actual value never appears in a prompt, a transcript, or the skill's own files. Agents and automation jobs both read secrets this way. See How a secret reaches an agent for the full mechanism.

Manage secrets on the Connect page (the Connect item in the left navigation), under the Secrets tab. Like every credential C3 AI Agentix stores, a secret is encrypted at rest and write-only: once you save it, the value is never rendered back in the UI or returned over the API. To change one, you save a new value over it.

How a secret reaches an agent

Inside an agent's session, C3 AI Agentix exposes each secret as an environment variable, ready for any skill, script, or tool the agent runs. That is why a secret's key must be a valid environment-variable name — letters, digits, and underscores, not starting with a digit.

C3 AI Agentix injects the value only into the running session. The agent can reference the variable, but the plaintext never passes through the model's prompt or the chat transcript. A skill references it the way any program references an environment variable, for example $GITHUB_TOKEN in a shell script or os.environ["GITHUB_TOKEN"] in Python.

Personal and Global scope

Each secret has a scope that decides whose sessions receive it.

  • Personal: only you receive it, in your own chats and automation jobs. You manage it yourself.
  • Global: every user's sessions across the cluster receive it. Only administrators can manage it.

Any user can add personal secrets for their own sessions. Creating or changing a global secret requires the Agentix.AppAdmin role, because it affects everyone.

When a personal and a global secret share the same key, the personal value wins in your sessions — so you can override a shared default with your own credential without an administrator's involvement.

Add a secret

Add a secret from the Connect page, choosing a scope if you have the admin role:

  1. Open Connect from the left navigation and select the Secrets tab.
  2. Select Add a secret.
  3. Enter the key (a valid environment-variable name) and its value.
  4. If you are an administrator, choose the scope: Personal or Global. Without the admin role there is no scope selector; the secret is always personal.
  5. Select save. The secret joins the list, showing its key and scope but never its value.

The Add a secret dialog on the Connect page

Rotate or remove a secret

Rotating and removing a secret both work from the same list on the Connect page:

  • Rotate: save a new value under an existing key. Saving over a key overwrites its value, which is exactly how you rotate a credential. The new value reaches every session that can see it, including one already running.
  • Remove: delete the secret from the list. Without the admin role, you can only remove your own personal secrets; the list never shows other users' personal secrets, and removing a global secret requires the Agentix.AppAdmin role.

Permissions

Two roles gate what you can do with secrets:

  • Agentix.User: add, rotate, and remove personal secrets, which reach only your own sessions and jobs.
  • Agentix.AppAdmin: also add, rotate, and remove global secrets, which reach every user's sessions across the cluster.

For the full role ladder, see Roles and Permissions.

Where to go next

Was this page helpful?