Credentials and configuration

Credential boundaries

Credential or value	Stored or supplied	Visible after write	Used by
Studio access token	Random per launch; carried in the loopback URL and local requests	Printed only for CLI launches that do not open the browser	Protects one 127.0.0.1 Studio HTTP/WebSocket server
Cached Sapiom sign-in	Current environment entry in ~/.sapiom/credentials.json	Account identity is visible; protect the file because it contains an API key	Desktop Studio, npx Studio, and the local @sapiom/mcp authoring server
Standalone SDK API key	Explicit createClient({ apiKey }) argument or SAPIOM_API_KEY	Available to that process	Direct @sapiom/tools capability calls
Runtime-injected agent key	Supplied by Sapiom inside a production run	Not returned to agent source or stored in the project	The production step’s ctx.sapiom client
Agent secret	Written to one cloud agent definition	Key name only	Production step processes as process.env[KEY]
Runtime default	Stored separately on one cloud definition	Path and value are readable	Entry input for supported future run starts
Caller input	Sent by the run initiator	Recorded as effective run input	One execution

The Studio access token and the Sapiom API key are not interchangeable. sapiom.json contains project identity and resources, never either credential.

Studio and authoring-MCP sign-in

npx launch behavior

• With a cached credential, Studio reuses it without opening OAuth.
• With no cache, a normal launch opens signed out.
• --login starts browser OAuth only when no credential is cached; it does not force a fresh login.
• --no-auth skips credential file and authentication network access during startup. It does not remove the in-app Connect account action.

The desktop app probes the same cache. On a clean non-test launch, it starts browser authentication before opening its main window. If authentication is cancelled, times out, or is otherwise unavailable, the desktop opens signed out for local work and keeps Connect account available for a later retry.

Authoring MCP tools

Tool	Effect
sapiom_authenticate	Opens browser authentication and writes the current environment’s cache entry.
sapiom_status	Reports the selected environment and whether a credential is available.
sapiom_logout	Clears the cached credential for the selected environment.

Keep ~/.sapiom/credentials.json private. Studio creates it with owner-only permissions, but backups, shell history, and copied diagnostics can still expose it. Never paste its contents into an issue or prompt.

Standalone @sapiom/tools authentication

Create an explicit client:

import { createClient } from "@sapiom/tools";

const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });

Or import a namespace directly after setting SAPIOM_API_KEY:

import { sandboxes } from "@sapiom/tools";

const sandbox = await sandboxes.create({ name: "docs-example" });

Standalone @sapiom/tools code does not automatically read the Studio/authoring-MCP credential cache. Inside a production agent step, prefer the runtime-injected ctx.sapiom client instead of constructing another client or embedding a key.

Authentication by action

Action	Sapiom sign-in required?	Notes
Open/edit a local project	No	Coding-agent authentication is separate and belongs to Claude Code.
Check or Local Run	No	Local Run inherits ordinary host process environment; it does not download cloud secrets.
Browse the live template gallery	Yes	Bundled offline starters remain available without Sapiom authentication.
Link, deploy, or Prod Run	Yes	Deploy can use metered cloud build compute; production calls are live.
Inspect, signal, or manage schedules	Yes	These operate organization-owned cloud state.
Hosted MCP	Yes	Configure that remote MCP independently from the local authoring MCP.
Standalone @sapiom/tools	Yes	Supply an API key explicitly or through SAPIOM_API_KEY.

Agent secrets

Secrets are scoped to a cloud definition. The read contract is names-only: GET /v1/workflows/definitions/:id/secrets returns { "keys": [...] }, while writes and deletes return no value. There is no supported read-back path.

Key contract

• use a JavaScript environment identifier beginning with a letter or underscore;
• the dashboard normalizes entry to uppercase A-Z, 0-9, and _;
• maximum key length is 256 characters;
• PATH, names beginning SAPIOM_ or WORKFLOWS_, and prototype-related keys are reserved;
• one definition can configure at most 256 keys;
• a value can contain up to 16,000 characters.

The dashboard’s .env import preserves each accepted secret value rather than trimming it. Invalid lines can be reported without echoing their value.

At every production step dispatch, the runtime resolves that definition’s configured values and injects them into the step process. An undeclared or unconfigured key is absent. Replacing or deleting a key affects later step dispatches; it does not mutate a process already running.

Server-side reuse copies a value from one owned definition to another. It is not a live reference. Each copy must be rotated or deleted independently.

Runtime defaults

Runtime defaults are non-secret values stored separately from agent secrets. The read endpoint returns only rows a user explicitly set, including each dotted path, value, and last-update time. An untouched declared default has no stored row.

Supported stored value shapes are:

• string, including email and cron text;
• finite number;
• boolean;
• flat array of strings.

A path is one or more JavaScript-identifier segments, such as deliverTo or client.email. Objects belong in the path structure, not in the stored value. Prototype-related path segments are rejected.

Saving null or omitting a setting value resets that path by deleting its stored row. false, 0, and a non-empty string are real stored values, not resets.

Merge precedence

Supported customer run starts assemble input in this order, with later layers winning:

template defaultInput
  → template settings[].default
  → stored definition values
  → caller input
  → entry-step Zod parse

Stored values are read at run start. They take effect on the next supported run without a deploy and do not modify an execution already started.

Trigger coverage

This merge currently runs for the customer execution endpoint used by Agent Studio Prod Run, the local authoring MCP, and dashboard Run once. The hosted sapiom_workflow_run operation bypasses it. Schedules execute the input captured when the trigger was created, so re-arm a schedule to change what it sends.

Template manifests can declare requiredSecrets, settings, and defaultInput. The current hand-authored defineAgent manifest does not export those declarations. Its entry Zod schema and caller input remain authoritative; do not invent defineAgent properties to configure the dashboard.