Skip to main content

Publish a connector

Third-party developers can list their own service in the Workspaces integrations catalog. Once a Burdenoff reviewer approves a submission, every workspace can find the connector under Integrations > Providers and connect to it with its own credentials.

What you can publish today​

A connector describes one public HTTPS API and how a workspace authenticates against it. Three authentication types are accepted:

TypeWhat the workspace entersHow it is sent
API keyOne secret keyIn the header or query parameter you name, optionally after a prefix such as Token
Bearer tokenOne access tokenAuthorization: Bearer <token>
Basic authUsername and passwordAuthorization: Basic <base64(username:password)>

The platform stores each workspace's credential encrypted and attaches it only to requests that workflows and integrations send to your API. You never receive credentials from Burdenoff; your API receives them from the workspace's own requests, exactly as if the workspace had called you directly.

OAuth 2.0 connectors are not accepted yet, because they need a client secret held by the platform for every environment. Until then, build an OAuth integration with a Burdenoff app in the developer portal or offer an API key alongside your OAuth flow.

Submit a connector​

  1. Open Integrations > Providers and select Publish a connector (or go to /integrations/developer/connectors in the app).
  2. Select Submit a connector and fill in the form:
    • Name, description (10 to 1000 characters) and category.
    • Icon (optional): an https image URL or an iconify:<set>:<name> icon, and an optional brand color as #RRGGBB.
    • Catalog key: a lowercase slug such as acme-crm. It becomes the connector's permanent identifier. Keys that start with generic-, http-, burdenoff, boff-, workspaces-, platform- or internal- are reserved.
    • API base URL, website and API docs URL: https URLs on public host names. IP addresses, localhost and internal suffixes such as .internal or .local are refused.
    • Authentication and, for an API key, where it is sent.
    • Publisher: your company name, a support email address, your privacy policy and optionally your terms of service and source repository.
  3. Accept the Connector Developer Terms below and select Submit for review.

You can have up to ten submissions waiting for review at a time, and only one submission per catalog key can wait for review.

From the API​

The same flow is available on the Workspaces GraphQL gateway (https://graphqlworkspaces.burdenoff.com/workspaces/graphql) for any signed-in user:

mutation Submit($input: SubmitConnectorInput!) {
  submitConnector(input: $input) {
    id
    key
    status
    reviewDueAt
  }
}
{
  "input": {
    "key": "acme-crm",
    "name": "Acme CRM",
    "description": "Sync contacts and deals from Acme CRM.",
    "category": "CRM",
    "authType": "API_KEY",
    "apiKeyPlacement": "HEADER",
    "apiKeyName": "X-Api-Key",
    "website": "https://acme.example.com",
    "docsUrl": "https://docs.acme.example.com/api",
    "baseUrl": "https://api.acme.example.com/v2",
    "publisherName": "Acme Inc.",
    "supportEmail": "[email protected]",
    "privacyPolicyUrl": "https://acme.example.com/privacy"
  }
}

Follow your submissions with myConnectorSubmissions and myConnectorSubmission(id:), and withdraw one that is still waiting with withdrawConnectorSubmission(id:). Each of these only ever returns or changes your own submissions. Invalid input is refused with BAD_USER_INPUT, and the error's extensions.field names the field to fix.

Review​

Every submission is reviewed by a Burdenoff platform reviewer. The review service level is five business days (Monday to Friday) from submission; the due time is shown on each submission as reviewDueAt, and reviewers see overdue submissions first.

A reviewer checks that:

  • the connector names a real, public API that you are entitled to publish a connector for;
  • the website, API docs, privacy policy and support address work;
  • the credential placement matches the API documentation;
  • the name, icon and description are accurate and do not imitate another company's product.

The outcome is one of:

  • Approved: the connector is installed in the catalog for every workspace, marked as third-party with your publisher name. The submission shows View listing.
  • Rejected: the submission shows the reviewer's reason. Fix the issue and submit again; the key is free again once a submission is decided.

Connector Developer Terms​

By submitting a connector you agree that:

  1. Authority. You are authorised to publish a connector for the service you describe, and the information you submit is accurate and kept accurate.
  2. Credentials and data. Workspaces send their own credentials and data to your API. You process them only to provide your service to that workspace, under your published privacy policy and applicable data protection law. You do not ask Burdenoff for workspace credentials or data.
  3. Availability and support. You keep your API documentation and the support address working, and you tell workspaces about breaking changes in your API through your own channels.
  4. Listing content. Your name, logo, icon and descriptions do not infringe anyone's rights and do not suggest an endorsement by Burdenoff or by another company.
  5. Price. Listing a connector in the catalog is free. Burdenoff takes no share of what your own service charges workspaces.
  6. Governance. Burdenoff may reject a submission, and may disable or remove a published connector at any time, for example when its API stops working, its links break, it is reported for abuse, or it breaks these terms. Workspaces keep control of their connections and can delete them at any time.
  7. No warranty. The catalog lists connectors as provided by their publishers. Burdenoff does not warrant third-party services.

These terms supplement the Burdenoff Terms of Service. Selling paid apps, templates or agents in the store is covered separately by the Developer Agreement. Questions: [email protected].