Skip to main content
These admin routes, under /api/v3/environment-connections (at v2, /api/v2/environments/admin/*), manage the workspace’s Environment Connections for a platform API key. The writes need environments:manage and the list needs environments:read, each at platform scope. An External App is refused with 403, even when it holds the permission. Each write takes an Idempotency-Key. Every route is reachable from MCP through forge_call_operation in the connections tool group.

Environment Connections

  • List the workspace’s connections. A connection’s credential is answered only as its managed secret’s id, never its value, and who created a connection is not answered.
  • Create a connection to Convex, GitHub or Vercel by name, without a credential; the answer is its connectionId. A connection’s config is refused, as in the Console.
  • Rename a connection by its connectionId. A connection that does not exist answers 404.
A key has no home of its own, so a connection it creates is homed at the deployment root.

Credentials

  • Create a connection with its credential, or replace a connection’s credential. The credential is stored as a managed secret, under the same secret identity on a replace, and is never answered.
  • Remove a connection: its credential, if it has one, is revoked and the connection is deleted. A connection that Environment Instances use is refused with 409; remove them first. A connection that does not exist is already removed and answers null.
Each credential write names an operationId, secretop_ followed by a UUID, that it records before it touches the secrets store. A retry by the same key with the same operationId resumes that write rather than starting another. An operationId started for a different write, or by a different key or person, is refused with 409. A write whose outcome at the secrets store is not yet known is answered 409 until it is reconciled. A platform API key’s writes are recorded under the key: it is the connection’s creator, and the requester of its managed secret and of the secret’s operation. A Personal key acts as its owner, so its writes are recorded under the owner. These writes record no audit event, for a key or for a person in the Console.

Not on these routes

Vaults, vault secrets, secret mappings, environment instances and their members are decided by each vault’s own member roles, which only a person holds, so they stay in the Console.