Version
GET

Get one connector

/v1/connectors/{key} in the Connectors API.

One card by key, registered or on the roadmap, in the shape the directory lists.

curl https://api.subscriby.net/v1/connectors/example \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

The manifest

Every key from install_mode onward describes what a registered connector can do; a roadmap card has them null or empty.

  • install_mode: paste_credential (the creator pastes a token the platform issued), oauth (the creator authorises an app), shared_platform (Subscriby runs one shared presence; nothing to connect).
  • scopes: project for an installation a creator sets up on a project; platform for a presence Subscriby itself runs on the connector.
  • resource_kinds: the kinds of place the connector gates, with the creator-facing label, the portal_label members see, an icon slug, the grant_mode (bearer_link: a single-use link; membership: the connector admits the member itself; role: a role is granted; creator_task: the creator hands access over by hand), whether a grant can be held ahead of a pass window (supports_early_admission_hold), the kind of the same connector a place of this kind can be an in-place upgrade of (upgrades_from, or null), and the shapes of plan a place of the kind can be sold under (plan_kinds: one_time, recurring, pass, pass_series, in that order). A resource's kind on the Resources endpoints is <key>:<kind>, and the same spelling is what a link request takes. Labels are translated into the token holder's language.
  • capabilities: the port families the connector implements: messaging, broadcasts, access_control, early_admission_hold, support_relay, native_payments, portal_login, creator_registration, management_surface, recovery_probes, recovery_standby_installations, recovery_resource_standby, recovery_mirror, recovery_identity_relink.
  • messaging and pacing: the limits every message and every bulk send is checked against.
  • management_commands and missing_commands: which core commands the connector's in-chat surface renders and which it does not; the docs' capability matrix and the Connectors tab show the gaps from these.
  • recovery: which Disaster Recovery facets the connector implements.
  • portal_cta: the button the member portal shows to open the connector (label, translated, and icon), or null when the connector has nowhere to open; the portal addresses it through the installation's start link.
  • install_fields and settings_fields: the declarative forms. Each field carries type (text, secret, select, toggle, instructions, link), a translated label and help, required, the validation rules, options for a select, a default value, the numbered walkthrough steps (with :app and :button placeholders for the app's name and the submit button's label) and links naming the text a renderer turns into a link. Render them in order and you have the connect form the dashboard shows.
GET
/v1/connectors/{key}

The token must hold this ability, or the call is refused with 403.

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken
AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

key*string

The connector key from the route.

Responses

200OK

200 with the card.

401Unauthorized

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

403Forbidden

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

404Not found

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. On this endpoint: RESOURCE_NOT_FOUND: when nothing is known by that key; error.context.connector echoes it.

429Too many requests

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

How is this guide?

Last updated on