Connector Instances

Create connector instance

Changed on

Create a connector instance from a registry type.<br><br> <b>Body:</b><br> Put the auth fields the registry schema lists for <code>authType</code> in <code>config.auth</code>, flat, and the connector's own sync settings in <code>config.sync</code>. A connector that needs no OAuth sign-in is configured on creation.<br><br> <b>OAuth:</b><br> An admin may send the OAuth app's credentials in <code>config.auth</code>: the app is saved and linked. Anyone may send <code>config.auth.oauthConfigId</code> to use a saved app; non-admins must. Send <code>baseUrl</code>: the provider redirects to <code>{baseUrl}/{redirectUri}</code>.<br><br> <b>Scope Permissions:</b><br>

<ul> <li><code>team</code> scope requires admin privileges</li> <li><code>personal</code> scope available to all users</li> </ul> <b>Next Steps After Creation:</b><br> <ol> <li>OAuth only: <code>GET /{id}/oauth/authorize</code>, then <code>GET /oauth/callback</code></li> <li>Optionally set sync and filters via <code>PUT /{id}/config/filters-sync</code></li> <li>Turn sync on via <code>POST /{id}/toggle</code></li> </ol>
post/connectors

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/connectors
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: /api/v1/oauth2/authorize
      Client credentials
      Token URL: /api/v1/oauth2/token scopes: connector:write

Request body

connectorTypestring required

type from the registry

instanceNamestring required
scope'team' | 'personal' required

Scope determines visibility and access control for connectors:<br>

<ul> <li><code>team</code> - Available to all users in the organization (admin-only creation)</li> <li><code>personal</code> - Private to the creating user only</li> </ul>
authType'OAUTH' | 'OAUTH_ADMIN_CONSENT' | 'API_TOKEN' | 'BEARER_TOKEN' | 'BASIC_AUTH' | 'ACCESS_KEY' | 'IAM_ROLE' | 'ACCOUNT_KEY' | 'CONNECTION_STRING' | 'ENTRA_ID' | 'CUSTOM' | 'NONE'

How a connector instance signs in to its source. Each connector type supports a subset; see supportedAuthTypes in the registry.

baseUrlstring

Origin of the page the OAuth provider redirects back to. The redirect URI is {baseUrl}/{redirectUri}; defaults to the PipesHub frontend URL.

Example request

{
  "scope": "team",
  "config": {
    "auth": {
      "baseUrl": "https://mycompany.atlassian.net",
      "email": "admin@mycompany.com",
      "apiToken": "ATATT3x..."
    }
  }
}

Response

Connector instance created. It is not syncing yet.

successboolean required
messagestring

Example response

{
  "connector": {
    "connectorId": "7b387394-1248-4fb6-810d-e8ac9ac226eb",
    "scope": "team"
  },
  "message": "Connector instance created successfully."
}

Changes

    • breaking

      added the pattern \S to the request property

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property ///

    • info

      the request property format was generalized from uri to no format

    • info

      added the new ENTRA_ID enum value to the request property ////

    • info

      added the new IAM_ROLE enum value to the request property ////