Secret Input

Collect API keys, passwords, and tokens from users via a form.

The simplest auth mode. You declare form fields, the user fills them in, and the values are encrypted and stored in the credential vault.

Manifest declaration

{
  "connections": [
    {
      "id": "weather_api",
      "display_name": "Weather Service",
      "auth_mode": "secret_input",
      "fields": [
        { "name": "api_key", "label": "API Key", "secret": true },
        { "name": "api_secret", "label": "API Secret", "secret": true }
      ]
    }
  ]
}

User experience

During pre-collection, if the user has no stored credential for this connection, the platform renders a form:

┌─────────────────────────────────────────────────┐
│  Weather Reporter needs your Weather Service     │
│  API credentials.                                │
│                                                  │
│  API Key:     [________________________]         │
│  API Secret:  [________________________]         │
│                                                  │
│  [Submit]                                        │
└─────────────────────────────────────────────────┘

If the user already has a credential stored for a different agent with the same connection ID:

┌─────────────────────────────────────────────────┐
│  Weather Reporter needs your Weather Service     │
│  credentials.                                    │
│  You already have Weather Service credentials on │
│  file.                                           │
│                                                  │
│  [Use existing credential]  [Enter new keys]     │
└─────────────────────────────────────────────────┘

Agent code

async def run(ctx: AgentContext):
    weather = await ctx.connect("weather_api")
    api_key = weather.get("api_key")
    api_secret = weather.get("api_secret")

ctx.connect() returns a dictionary-like object with the field values. It never blocks — the pre-collection model guarantees the values are present before the sandbox starts.

Delivery modes

You can choose how secret input credentials are delivered to the agent.

Runtime object (default)

Accessed via ctx.connect(). The SDK fetches credentials from a platform-injected runtime config.

{ "delivery": "runtime_object" }

Environment variables

Injected as env vars. You declare the mapping:

{
  "delivery": "env_vars",
  "env_map": {
    "api_key": "WEATHER_API_KEY",
    "api_secret": "WEATHER_API_SECRET"
  }
}

File

Written to /tmp/grexal/{connection_id}.json inside the sandbox.

{ "delivery": "file" }

Field reference

Field	Type	Required	Default	Description
`fields`	`object[]`	Yes	—	Form fields to collect. At least 1, at most 20.
`fields[].name`	`string`	Yes	—	Field key. Used in `conn.get(name)`. Must match `^[a-z][a-z0-9_]*$`.
`fields[].label`	`string`	Yes	—	User-facing label shown in the form.
`fields[].secret`	`boolean`	No	`true`	Whether to mask the input.
`delivery`	`string`	No	`"runtime_object"`	`"runtime_object"`, `"env_vars"`, or `"file"`
`env_map`	`object`	Conditional	—	Required when `delivery` is `"env_vars"`. Maps field names to env var names.