Set or remove Agent secrets
Set write-only Agent environment secrets or remove configured names, then restart that Agent's gateway so the new environment takes effect. Workspace owner/admin permission is required.
API 2.7.0 · Published service contract ↗
Request
Base URL: https://app.sym.so/v1/workspaces/{workspace_id}
Authentication: bearer. Required scope: secrets:write.
POST /agents/{agent_id}/secrets
Set write-only Agent environment secrets or remove configured names, then restart that Agent's gateway so the new environment takes effect. Workspace owner/admin permission is required.
| Parameter | Type | Description |
|---|---|---|
agent_idpath · required | string | Required agent_id path identifier. |
curl --fail-with-body -X POST "https://app.sym.so/v1/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/secrets" \
-H "Authorization: Bearer $SYM_WORKSPACE_API_KEY" \
-H "Content-Type: application/json" \
--data "{\"values\":{\"EXAMPLE_SERVICE_TOKEN\":\"<secret supplied at runtime>\"},\"unset\":[\"OBSOLETE_SERVICE_TOKEN\"]}"{
"worker_id": "worker-example-001",
"org_id": "workspace_example",
"data": {
"profile_id": "agent_example",
"delivery": "process_environment",
"secrets": [
{
"name": "EXAMPLE_SERVICE_TOKEN",
"configured": true,
"reference": "EXAMPLE_SERVICE_TOKEN is available as an environment variable in Agent agent_example's runtime. Use the process environment; do not search for a file or print its value."
}
],
"configured_count": 1,
"activation": {
"state": "active",
"delivery": "process_environment"
},
"gateway_restart": {
"ok": true,
"service": "hermes-gateway-agent_example"
}
},
"ok": true
}Authorization
{
"type": "bearer",
"scope": "secrets:write",
"transport": "Authorization: Bearer <workspace_api_key>"
}Errors
| Status | Description |
|---|---|
| 400 | The request body or parameters are invalid. |
| 401 | The workspace API key is missing, invalid, expired, or revoked. |
| 403 | The key lacks the required scope or its owner no longer has permission. |
| 404 | The resource is missing or intentionally hidden by authorization. |
| 429 | The key exceeded its current rate limit. |
| 503 | The secret was saved but Gateway activation failed; retry is required. |
Usage notes
- Only uppercase environment-style names accepted by SYM-node may be written.
- HTTP 200 means the Agent environment is active; failed activation returns HTTP 503/pending instead of false success.
- The response confirms configuration state but never echoes supplied values.