Gateway settings decide whether a service agent may use an external tool, must wait for approval, or is denied. These endpoints manage connectors, managed secrets, installable policy packs, simulations, and emergency freezes for the selected workspace.
Configuration and secret material are separated
Connector JSON redacts recognized sensitive config keys. Writing a config back with a [REDACTED] value keeps the stored value at that key. Managed-secret reads expose lifecycle metadata, not stored values; neither response is a secret backup.
Simulation never executes
A simulation explains matching rules and the resulting decision without running the action. A freeze overrides normal traffic until expiry or manual lift.
Custom access rules use the console
Operator JSON has no CRUD for individual grants or approval policies. Manage them at /app/gateway/access and /app/gateway/policies; JSON pack routes create or install reusable template packs.
Before you begin
A signed-in browser session with a selected workspace backed by an active membership is required; an archived workspace remains readable but rejects mutations. Every /api/v1/operator endpoint rejects API credentials and bearer tokens, regardless of their scopes.
Any role on an active membership can read gateway configuration. Owner or admin membership is required for mutations to connectors, managed secrets, policy packs, simulations, and freeze settings.
Know the connector actions and target agent or role before configuring access.
How it works
Model before enabling
Configure the connector at /app/gateway/connectors. Add custom rules in their console pages or install a template pack, then simulate representative actions before live traffic.
Respond conservatively
Create the narrowest freeze that contains an incident, inspect audit and violations, and lift it only after remediation. Read-only GET requests do not need a CSRF token. A mutating operator request needs the browser session cookie and current Phoenix CSRF token supplied by the product UI or another authorized same-origin client; do not substitute bearer authentication.
Examples
These examples are illustrative. Replace the sample values with your own.
Keep credentials in environment variables or a secret manager, never in client-side code.
Inventory configured connectors
Recognized sensitive config keys become [REDACTED]. Treat remaining configuration as sensitive because heuristic matching cannot identify every secret.
javascript
const response = await fetch("/api/v1/operator/connectors", {
credentials: "same-origin",
headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);
What to expect
200 OK with {"connectors": []} when none are configured. Sensitive config keys in populated records are replaced with [REDACTED].
Troubleshooting
A simulated action is denied
Inspect matched grants, selected policy, and unevaluable conditions. Missing environment operands fail closed; provide the same bounded context the real action will carry.
A freeze cannot be created or lifted
Only owners and admins may manage freezes. Repeating a matching freeze returns the existing active freeze rather than stacking or conflicting; a missing scoped object returns 404, and archived workspaces reject mutation.
Endpoint reference
Ready to integrate? Open an endpoint for its required permissions, request fields,
response format, and status codes. The examples above explain the workflow;
these details define each individual request.
GET
/api/v1/operator/connector_templates
Web Session
List connector catalog entries
Description
Returns built-in connector catalog entries with setup recipes, auth field schemas, supported environments, and linked policy template packs.
Auth
Web Session
Responses
200
List of connector catalog entries
Returns: ConnectorTemplateList
GET
/api/v1/operator/connectors
Web Session
List connectors
Description
Returns all connectors in the current workspace: active, paused and archived. Archived (deleted) connectors carry `archived_at` and are excluded from gateway checks.
Auth
Web Session
Responses
200
List of connectors
Returns: ConnectorList
POST
/api/v1/operator/connectors
Web Session
Create connector
Description
Creates a new connector in the current workspace. The slug is auto-generated from the name if not provided.
Auth
Web Session
Request Body
Field
Type
Required
Description
name
string
Yes
Connector display name
status
string (active, paused)
No
Initial status
config
object
No
Connector-specific configuration
description
string
No
Connector description
category
string
No
Connector category (e.g., 'email', 'custom')
slug
string
No
URL-safe slug (auto-generated from name if omitted)
Responses
201
Connector created
Returns: Connector
422
Validation error
GET
/api/v1/operator/connectors/:id
Web Session
Get connector details
Description
Returns details of a specific connector.
Auth
Web Session
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
Connector UUID
Responses
200
Connector details
Returns: Connector
404
Connector not found
PATCH
/api/v1/operator/connectors/:id
Web Session
Update connector
Description
Updates a connector's configuration. Accepts either top-level fields or a 'connector' wrapper key. `config` replaces the stored map; a value sent back as the `[REDACTED]` placeholder keeps the stored value at that key.
Auth
Web Session
Request Body
Field
Type
Required
Description
name
string
No
Connector display name
status
string (active, paused)
No
Connector status
config
object
No
Connector-specific configuration
description
string
No
Connector description
category
string
No
Connector category
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
Connector UUID
Responses
200
Connector updated
Returns: Connector
404
Connector not found
DELETE
/api/v1/operator/connectors/:id
Web Session
Delete (archive) connector
Description
Archives a connector. The connector is soft-deleted by setting archived_at. Archived connectors are excluded from gateway authorization checks.
Auth
Web Session
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
Connector UUID
Responses
200
Connector archived
Returns: Connector
404
Connector not found
GET
/api/v1/operator/policy_template_packs
Web Session
List policy template packs
Description
Returns built-in policy packs plus installation state for the current workspace.
Auth
Web Session
Responses
200
List of policy template packs
Returns: PolicyTemplatePackList
POST
/api/v1/operator/policy_template_packs
Web Session
Create policy template pack
Description
Creates a new custom policy template pack in the current workspace. Requires workspace admin privileges.
Auth
Web Session
Request Body
Field
Type
Required
Description
name
string
Yes
Policy pack name
status
string (draft, published, archived)
No
Pack status
version
string
No
Pack version (default: '1.0.0')
description
string
No
Policy pack description
category
string
No
Policy pack category
connectors
object
No
Connector definitions linked to this pack
grants
object
No
Permission grant rules
policies
object
No
Policy rule definitions
Responses
201
Policy template pack created
Returns: PolicyTemplatePack
422
Validation error
POST
/api/v1/operator/policy_template_packs/:id/install
Web Session
Install a policy template pack
Description
Installs a built-in policy pack into the current workspace. Installs are idempotent per pack version.
Auth
Web Session
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
Policy pack identifier
Responses
201
Policy template pack installed
Returns: PolicyTemplatePack
400
unsupported_pack_format: a custom pack with connectors, grants or policies cannot be installed
404
Policy template pack not found
GET
/api/v1/operator/managed_secrets
Web Session
List managed secrets
Description
Returns workspace-managed secret references used by workflow targets and other operator-configured integrations.
Auth
Web Session
Responses
200
List of managed secrets
Returns: ManagedSecretList
POST
/api/v1/operator/managed_secrets
Web Session
Create a managed secret
Description
Stores a managed secret through the configured provider and returns a workspace-scoped reference record.
Auth
Web Session
Request Body
Field
Type
Required
Description
name
string
Yes
Display name for the secret
value
string
Yes
Plaintext secret value
slug
string
No
Optional URL-safe secret slug
provider_key
string
No
Optional provider-side storage key
purpose
string
No
Operator-defined purpose label
Responses
201
Managed secret created
Returns: ManagedSecret
400
invalid_secret_value (value missing or blank), or provider_key_taken (provider_key already holds a secret)
422
Changeset validation error (for example a missing name)
POST
/api/v1/operator/managed_secrets/:id/rotate
Web Session
Rotate a managed secret
Description
Rotates the underlying provider value for a managed secret and increments its recorded version.
Auth
Web Session
Request Body
Field
Type
Required
Description
value
string
Yes
Replacement plaintext value
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
Managed secret UUID
Responses
200
Managed secret rotated
Returns: ManagedSecret
400
invalid_secret_value (value missing or blank)
404
Managed secret not found
422
Changeset validation error
POST
/api/v1/operator/policy_simulations
Web Session
Simulate a gateway policy decision
Description
Runs a dry-run authorization decision with condition explanations. The fields go inside a `simulation` object; a body without it returns 400 `invalid_simulation_payload`.
Auth
Web Session
Request Body
Field
Type
Required
Description
simulation
object
Yes
Simulation input
simulation.action
string
No
Alias of action_name
simulation.amount
number
No
Amount for amount conditions
simulation.payload
object
No
Action payload matched by policy conditions
simulation.action_name
string
No
Action to simulate (this or `action` is required)
simulation.environment
string
No
Target environment
simulation.service_agent_id
string
No
Service agent UUID when actor_type is service_agent
simulation.connector_id
string
No
Connector UUID
simulation.connector_slug
string
No
Connector slug (alternative to connector_id)
simulation.risk_score
number
No
Risk score for risk_score_gte conditions
simulation.actor_type
string
No
`service_agent` to simulate an agent; otherwise the caller
Responses
200
Simulation result
400
invalid_simulation_payload (no simulation object), invalid_action_name (no action), or invalid_service_agent (actor_type service_agent with a missing, malformed or foreign service_agent_id)
404
Connector not found
GET
/api/v1/operator/gateway_freezes
Web Session
List gateway freezes
Description
Returns gateway freezes newest first, active and historical. Always bounded: `limit` defaults to 25 and is clamped to 100. Each entry carries `active`, which is false once the freeze is lifted *or* once its `expires_at` has passed, even if the expiry sweeper has not stamped it yet.
Auth
Web Session
Parameters
Name
In
Type
Required
Description
status
query
string
No
Filter to freezes still in force, or to lifted ones
limit
query
integer
No
Maximum freezes to return (default 25, server maximum 100)
Stops gateway execution immediately for the whole workspace, one
connector, or one service agent. A `reason` is required.
A workspace freeze also refuses machine authentication: API requests and
agent socket connects for the workspace answer `403` with
`"error": "workspace_frozen"` while it is in force. Connector and
service-agent freezes are narrower — the credential still authenticates,
but every authorization decision for that scope is denied with
`decision_path: "frozen"`.
Freezing a scope that is already frozen returns the freeze already in
force rather than stacking a second one, so two responders hitting the
same button do not fragment the audit trail.
Requires an owner or admin membership.
Auth
Web Session
Request Body
Field
Type
Required
Description
reason
string
Yes
Why the gateway is being stopped (3-2000 characters)
expires_at
string
No
Optional automatic thaw time (ISO 8601, must be in the future)
service_agent_id
string
No
Service agent UUID; required when scope_type is "service_agent"
connector_id
string
No
Connector UUID; required when scope_type is "connector"
connector_id or service_agent_id is not in this workspace
422
Missing reason, or a scope target that does not match scope_type
POST
/api/v1/operator/gateway_freezes/:id/lift
Web Session
Lift a gateway freeze
Description
Ends a freeze and records who lifted it with `lift_kind: "manual"`. A freeze whose expiry has already passed but which the sweeper has not reached yet is still liftable and is recorded as a manual lift. Requires an owner or admin membership.
