Settings schema

JSON Schema describing per-installation connection settings — including encrypted secret fields.

Connectors use a JSON Schema document to describe the form an admin fills in to install a connection. The schema lives at connection.settingsSchema in the manifest. Plain extensions don’t have this — they use the simpler config defaults map (see Settings).

Real example

A real connector’s schema:

settingsSchema: {
  type: "object",
  required: ["api_key"],
  properties: {
    api_key: {
      type: "string",
      minLength: 1,
      title: "Secret API key",
      description:
        "Stripe restricted or secret API key used for poll and reconciliation routes.",
      "x-secret": true,
      "x-placeholder": "sk_live_... or sk_test_...",
    },
    webhook_secret: {
      type: "string",
      minLength: 1,
      title: "Webhook signing secret",
      description:
        "Stripe endpoint signing secret used by the verified webhook route.",
      "x-secret": true,
      "x-placeholder": "whsec_...",
    },
    account_id: {
      type: "string",
      title: "Connected account ID",
      description: "Optional Stripe Connect account ID...",
      "x-placeholder": "acct_...",
    },
    extract_tax_details: {
      type: "boolean",
      title: "Extract tax details",
      default: true,
    },
    settlement_currency: {
      type: "string",
      title: "Expected settlement currency",
      enum: ["auto", "USD", "EUR", "GBP", "CAD", "AUD", "JPY"],
      default: "auto",
    },
  },
},

Standard JSON Schema bits

type: "object" and a properties map — required.
required: [...] — fields that must be present.
Per-property: type (string | number | boolean | object | array), title, description, default.
Standard validators: minLength, maximum, enum, pattern, etc.

Backfill-specific extensions

Key	Effect
`x-secret: true`	The dashboard renders the field as a password input and stores the value in the encrypted secret store. The schema field name becomes the secret name (so `api_key` ends up readable as `Secrets.get("api_key")`).
`x-placeholder: "..."`	Placeholder text in the dashboard input.

x-secret is the bridge between the connector schema and the Secrets system. You don’t need to also list these names under permissions.secrets — by being declared in the connector’s settingsSchema, they’re owned by the connector.

Reading the values

Non-secret fields come back from Settings.getAll() exactly like a plain extension’s config:

const acctId = Settings.get("account_id");
const extractTax = Settings.get("extract_tax_details");

Secret fields are read with Secrets.get(...):

const apiKey = Secrets.get("api_key");
const webhookSecret = Secrets.get("webhook_secret");

What happens at install

The dashboard renders the form from the schema, validates the admin’s inputs against the schema, splits secret-marked values into the secret store, and persists the rest as the connection’s settings. From that point on, your runtime calls to Settings.get and Secrets.get see the values.

← Sync routes

OAuth →