Repository Registry

Define connectors alongside your widgets in a GitHub repository. Instead of creating each connector manually through the admin UI, add a connectors_registry.json file to your repository root and connectors are synced automatically on every push.

When to Use This

• You manage widgets in a GitHub repository (see Repository Layout) and want connectors defined in the same place
• You need consistent connector configurations across multiple communities
• You prefer managing connectors in version control

How it works

1. Add connectors_registry.json to your repository root (alongside extensions_registry.json)
2. Push to the watched branch
3. The platform validates the file and syncs connectors automatically
4. Synced connectors appear in the admin UI with a "GitHub" badge and cannot be edited there

The repository is the source of truth. On every push:

• New connector definitions are created
• Changed definitions are updated
• Definitions removed from the file are deleted
• Manually created connectors are never affected

Repository structure

your-repo/
├── extensions_registry.json          # Widget definitions
├── connectors_registry.json      # Connector definitions (optional)
└── widgets/
    └── my_widget/
        └── index.html

Schema

The file must be a JSON object with a connectors array:

{
  "connectors": [
    {
      "name": "Weather API",
      "url": "https://api.weather.com/v1/current",
      "method": "GET",
      "headers": [
        { "key": "Accept", "value": "application/json", "overridable": false }
      ],
      "query_parameters": [
        { "key": "location", "value": "{{ user.profile_fields.by_id(123) }}", "overridable": true }
      ],
      "authentication": {
        "type": "apikey",
        "config": {
          "key": "X-API-Key",
          "value": "{{ get_secret('weather_api_key') }}",
          "in": "header"
        }
      },
      "request_body": "",
      "response_body": "",
      "response_content_type": "",
      "permalink": "weather-api"
    }
  ]
}

Connector fields

Field	Type	Required	Default	Description
name	string	Yes	—	Display name (max 255 characters)
url	string	Yes	—	Target endpoint URL (max 2048 characters)
method	string	No	"GET"	HTTP method: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
headers	array	No	[]	Request headers — each key max 255, value max 1000 characters (see Headers & Query Parameters)
query_parameters	array	No	[]	URL query parameters — each key max 255, value max 1000 characters
authentication	object	No	none	Auth config (see Authentication)
request_body	string	No	""	Request transformation template (see Request Transformation)
response_body	string	No	""	Response body template (see Response Transformation)
response_content_type	string	No	""	Content-Type override for the response returned to the widget (max 255 characters)
permalink	string	No	auto-generated	URL-safe identifier (lowercase-with-dashes, max 255 characters)

Permalink

The permalink is the connector's identity during sync. If you omit it, one is generated from the name (e.g., "Weather API" becomes weather-api).

• Renaming a connector with the same permalink updates the existing connector
• Changing the permalink creates a new connector and deletes the old one
• Permalinks must match the pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$ and be at most 255 characters

Extra fields

You can copy JSON from the admin UI's Code Mode directly into the file. Any extra fields not listed above are silently ignored.

Secrets

Connector definitions can reference secrets using Jinja2 syntax:

{
  "name": "Salesforce Lookup",
  "url": "https://myorg.my.salesforce.com/services/data/v59.0/sobjects",
  "authentication": {
    "type": "oauth_client_credentials",
    "config": {
      "client_id": "{{ get_secret('salesforce_client_id') }}",
      "client_secret": "{{ get_secret('salesforce_client_secret') }}",
      "token_url": "https://login.salesforce.com/services/oauth2/token"
    }
  }
}

Secrets must be created in advance through the admin UI. See Secrets for details. The platform validates the connector schema, not secret existence.

WARNING

Never commit actual secret values in connectors_registry.json. Always use {{ get_secret('name') }} to reference secrets stored in the platform.

Protection

Connectors synced from a repository cannot be edited or deleted through the admin UI or API. All changes must come from the repository.

Multi-community repositories

When multiple communities subscribe to the same repository, each community gets its own independent set of connectors. Connectors are isolated per community just like widgets.

Error handling

A structural problem with the file fails the entire publish — no connectors are created, updated, or deleted. Hover over the build status icon for details. Causes:

• Invalid JSON — Syntax error in the file (missing comma, trailing comma, etc.)
• Missing required fields — A connector is missing name or url
• Duplicate permalinks — Two connectors in the same file share a permalink
• Permalink collision — A repository connector's permalink conflicts with a manually created connector. Rename or delete the existing connector to resolve.

A problem with a single connector's field values — for example a field that exceeds its length limit, a permalink that isn't a valid slug, or an invalid authentication config — skips just that connector. The build status shows a warning that names the connector and the field to fix, and the remaining connectors continue to sync.

Removing the file

If you delete connectors_registry.json from your repository, all connectors that were synced from that repository are deleted on the next push. Manually created connectors and connectors from other repositories are not affected.

An empty connectors array has the same effect:

{
  "connectors": []
}

Next Steps

• Repository Layout — How to set up your widget repository
• Configuration — Connector field details
• Authentication — Auth type options
• Secrets — Managing credentials
• Example connectors_registry.json in the template repository — Working connector definitions alongside widgets