diff --git a/server/src/__tests__/plugin-config-validator.test.ts b/server/src/__tests__/plugin-config-validator.test.ts
new file mode 100644
index 00000000000..e47eb8efe84
--- /dev/null
+++ b/server/src/__tests__/plugin-config-validator.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import type { JsonSchema } from "@paperclipai/shared";
+import { validateInstanceConfig } from "../services/plugin-config-validator.js";
+
+const SECRET_ID = "11111111-1111-4111-8111-111111111111";
+const binding = { type: "secret_ref", secretId: SECRET_ID, version: "latest" };
+
+// The shape plugin manifests use: a string field marked as a secret reference.
+const schema = {
+  type: "object",
+  properties: {
+    apiKey: { type: "string", title: "API key", format: "secret-ref" },
+    region: { type: "string" },
+    auth: {
+      type: "object",
+      properties: { token: { type: "string", format: "secret-ref" } },
+      additionalProperties: false,
+    },
+  },
+  required: ["apiKey"],
+  additionalProperties: false,
+} as unknown as JsonSchema;
+
+describe("validateInstanceConfig secret-ref fields", () => {
+  it("accepts the secret_ref binding object the settings form saves for a string secret-ref field", () => {
+    const configJson = { apiKey: binding, region: "us", auth: { token: { ...binding, version: 2 } } };
+    expect(validateInstanceConfig(configJson, schema)).toEqual({ valid: true });
+    // Validation does not rewrite what gets stored or sent to the worker.
+    expect(configJson.apiKey).toEqual(binding);
+  });
+
+  it("still enforces the rest of the schema around a binding", () => {
+    expect(validateInstanceConfig({ apiKey: binding, region: 5 }, schema)).toMatchObject({
+      valid: false,
+      errors: [{ field: "/region" }],
+    });
+    expect(validateInstanceConfig({ region: "us" }, schema).valid).toBe(false);
+  });
+
+  it("rejects objects that are not valid secret_ref bindings and objects in ordinary string fields", () => {
+    expect(validateInstanceConfig({ apiKey: { type: "secret_ref", secretId: "not-a-uuid" } }, schema)).toMatchObject({
+      valid: false,
+      errors: [{ field: "/apiKey", message: "must be string" }],
+    });
+    expect(validateInstanceConfig({ apiKey: binding, region: binding }, schema)).toMatchObject({
+      valid: false,
+      errors: [{ field: "/region", message: "must be string" }],
+    });
+  });
+});
+
+describe("validateInstanceConfig secret-ref array items", () => {
+  const arraySchema = {
+    type: "object",
+    properties: {
+      keys: { type: "array", items: { type: "string", format: "secret-ref" } },
+      accounts: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { name: { type: "string" }, token: { type: "string", format: "secret-ref" } },
+          required: ["name", "token"],
+          additionalProperties: false,
+        },
+      },
+    },
+    additionalProperties: false,
+  } as unknown as JsonSchema;
+
+  it("accepts bindings the settings form saves in array items and nested array objects", () => {
+    const configJson = {
+      keys: [binding, { ...binding, version: 3 }],
+      accounts: [{ name: "primary", token: binding }],
+    };
+    expect(validateInstanceConfig(configJson, arraySchema)).toEqual({ valid: true });
+    expect(configJson.keys[0]).toEqual(binding);
+    expect(configJson.accounts[0]!.token).toEqual(binding);
+  });
+
+  it("still rejects malformed bindings and wrong types inside arrays", () => {
+    expect(validateInstanceConfig({ keys: [binding, { type: "secret_ref", secretId: "nope" }] }, arraySchema)).toMatchObject({
+      valid: false,
+      errors: [{ field: "/keys/1", message: "must be string" }],
+    });
+    expect(validateInstanceConfig({ accounts: [{ name: binding, token: binding }] }, arraySchema)).toMatchObject({
+      valid: false,
+      errors: [{ field: "/accounts/0/name", message: "must be string" }],
+    });
+  });
+});
+
+describe("validateInstanceConfig secret-ref parsing matches the secrets handler", () => {
+  it("rejects a padded secret id that the secrets handler would also refuse", () => {
+    expect(validateInstanceConfig({ apiKey: { ...binding, secretId: ` ${SECRET_ID} ` } }, schema)).toMatchObject({
+      valid: false,
+      errors: [{ field: "/apiKey", message: "must be string" }],
+    });
+  });
+});
diff --git a/server/src/services/plugin-config-validator.ts b/server/src/services/plugin-config-validator.ts
index 6eb95aa0fb2..404cc4e0041 100644
--- a/server/src/services/plugin-config-validator.ts
+++ b/server/src/services/plugin-config-validator.ts
@@ -10,13 +10,57 @@
 
 import Ajv, { type ErrorObject } from "ajv";
 import addFormats from "ajv-formats";
-import type { JsonSchema } from "@paperclipai/shared";
+import { envBindingSecretRefSchema, type JsonSchema } from "@paperclipai/shared";
 
 export interface ConfigValidationResult {
   valid: boolean;
   errors?: { field: string; message: string }[];
 }
 
+/**
+ * Secret-ref fields are declared `type: "string"`, but the settings form and the
+ * plugin secrets API store the `{ type: "secret_ref", secretId, version }` binding
+ * object there. Validate the binding's secret id in its place so the schema
+ * checks the field without rejecting the only shape the secrets handler accepts.
+ * The walk follows object properties, array items and schema combinators, and
+ * accepts a binding only when the secrets handler's own parser accepts it.
+ */
+function secretRefsAsIds(value: unknown, schema: unknown): unknown {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return value;
+  const node = schema as Record<string, unknown>;
+
+  if (node.format === "secret-ref") {
+    const binding = envBindingSecretRefSchema.safeParse(value);
+    if (binding.success) return binding.data.secretId;
+  }
+
+  let result = value;
+  for (const keyword of ["allOf", "anyOf", "oneOf"] as const) {
+    const branches = node[keyword];
+    if (!Array.isArray(branches)) continue;
+    for (const branch of branches) result = secretRefsAsIds(result, branch);
+  }
+
+  if (Array.isArray(result)) {
+    const items = node.items;
+    if (items && typeof items === "object") {
+      const itemSchemaAt = (index: number) => (Array.isArray(items) ? items[index] : items);
+      result = result.map((item, index) => secretRefsAsIds(item, itemSchemaAt(index)));
+    }
+    return result;
+  }
+
+  const properties = node.properties;
+  if (result && typeof result === "object" && properties && typeof properties === "object") {
+    const record = { ...(result as Record<string, unknown>) };
+    for (const [key, propertySchema] of Object.entries(properties as Record<string, unknown>)) {
+      if (key in record) record[key] = secretRefsAsIds(record[key], propertySchema);
+    }
+    result = record;
+  }
+  return result;
+}
+
 /**
  * Validate a config object against a JSON Schema.
  *
@@ -39,7 +83,7 @@ export function validateInstanceConfig(
   // hint only — UUID validation happens in the secrets handler at resolve time.
   ajv.addFormat("secret-ref", { validate: () => true });
   const validate = ajv.compile(schema);
-  const valid = validate(configJson);
+  const valid = validate(secretRefsAsIds(configJson, schema));
 
   if (valid) {
     return { valid: true };