Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Create your own connector

Choose an auth type, build the connector payload, and create or manage custom connectors in Scalekit.

This page covers everything you need to create a custom connector: building the connector payload and managing it with the API.

Prerequisites

You need three credentials from your Scalekit environment:

  • SCALEKIT_ENVIRONMENT_URL — the base URL of your Scalekit environment
  • SCALEKIT_CLIENT_ID — your environment’s client ID
  • SCALEKIT_CLIENT_SECRET — your environment’s client secret

Find these in the Scalekit Dashboard under Developers → Settings → API Credentials.

Create a connector

Section titled “Create a connector”

Share the connector name, Scalekit credentials, and API docs. The skill infers the auth type, generates the payload, and walks you through create, update, and promotion to Production. Always review the final payload before approving.

To manage connectors directly via API, use the payloads below.

Understand the connector payload

Supported auth types are OAUTH, BASIC, BEARER, and API_KEY. Use OAUTH when the upstream API or MCP server requires a user authorization flow and token exchange. Use BASIC, BEARER, or API_KEY when it accepts static credentials or long-lived tokens.

MCP providers use the same four auth types as REST API providers, with is_mcp: true set in each auth_patterns[] entry. OAuth MCP connectors use a simplified oauth_config: {"pkce_enabled": true} — the MCP server handles authorization via Dynamic Client Registration. Non-OAuth MCP connectors omit oauth_config entirely.

The connector payload uses these common top-level fields:

  • display_name: Human-readable name for the custom connector
  • description: Short description of what the connector connects to
  • auth_patterns: Authentication options supported by the connector
  • proxy_url: Base URL the proxy should call for the upstream API (mandatory)
  • proxy_enabled: Whether the proxy is enabled for the connector (mandatory, should be true)

proxy_url can also include templated fields when the upstream API requires account-specific values, for example https://{{domain}}/api.

Within auth_patterns, the most common fields are:

  • type: The auth type, such as OAUTH, BASIC, BEARER, or API_KEY
  • display_name: Label shown for that auth option
  • description: Short explanation of the auth method
  • fields: Inputs collected for static auth providers such as BASIC, BEARER, and API_KEY. These usually store values such as username, password, token, api_key, domain, or version.
  • account_fields: Inputs collected for OAUTH connectors when account-scoped values are needed. This is typically used for values tied to a connected account, such as named path parameters.
  • oauth_config: OAuth-specific configuration, such as authorize and token endpoints
  • auth_header_key_override: Custom header name when the upstream does not use Authorization. For example, some APIs expect auth in a header such as X-API-Key instead of the standard Authorization header.
  • auth_field_mutations: Value transformations applied before the credential is sent. This is useful when the upstream expects a prefix, suffix, or default companion value, such as adding a token prefix or setting a fallback password value for Basic auth.
  • is_mcp: Set to true when the upstream is an MCP server. Tells Scalekit to route the connector through MCP tool calling instead of the HTTP proxy.

Below are example payloads for API and MCP connectors across all supported auth patterns.

{
  "display_name": "My Asana",
  "description": "Connect to Asana. Manage tasks, projects, teams, and workflow automation",
  "auth_patterns": [
    {
      "type": "OAUTH",
      "display_name": "OAuth 2.0",
      "description": "Authenticate with Asana using OAuth 2.0 for comprehensive project management",
      "fields": [],
      "oauth_config": {
        "authorize_uri": "https://app.asana.com/-/oauth_authorize",
        "token_uri": "https://app.asana.com/-/oauth_token",
        "user_info_uri": "https://app.asana.com/api/1.0/users/me",
        "available_scopes": [
          {
            "scope": "profile",
            "display_name": "Profile",
            "description": "Access user profile information",
            "required": true
          },
          {
            "scope": "email",
            "display_name": "Email",
            "description": "Access user email address",
            "required": true
          }
        ]
      }
    }
  ],
  "proxy_url": "https://app.asana.com/api",
  "proxy_enabled": true
}

Before submitting, review the final payload carefully:

  • display_name and description
  • The selected auth type
  • Required fields and account_fields
  • OAuth endpoints and scopes, if the connector uses OAuth
  • proxy_url
  • Whether is_mcp is set to true for MCP providers
Generate an access token

All API requests require a short-lived access token. Generate one using your SCALEKIT_CLIENT_ID and SCALEKIT_CLIENT_SECRET:

Terminal window
curl --location "$SCALEKIT_ENVIRONMENT_URL/oauth/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$SCALEKIT_CLIENT_ID" \
  --data-urlencode "client_secret=$SCALEKIT_CLIENT_SECRET"

Use the access_token value from the response as $env_access_token in the curl commands below.

Use the payload for your auth type as the request body in the create request:

Terminal window
curl --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers" \
  --header "Authorization: Bearer $env_access_token" \
  --header "Content-Type: application/json" \
  --data '{...}'

After the connector is created, create a connection in the Scalekit Dashboard and continue with the standard connector flow.

List connectors

Section titled “List connectors”

List existing connectors to confirm whether to create a new one or update an existing one.

Terminal window
curl --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/providers?filter.provider_type=CUSTOM&page_size=1000" \
  --header "Authorization: Bearer $env_access_token"

Update a connector

Section titled “Update a connector”

Use the List connectors API to get the connector identifier, then send the updated payload:

Terminal window
curl --location --request PUT "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
  --header "Authorization: Bearer $env_access_token" \
  --header "Content-Type: application/json" \
  --data '{...}'

Delete a connector

Section titled “Delete a connector”

Use the List connectors API to get the connector identifier. If the connector is still in use, remove the related connections or connected accounts first.

Terminal window
curl --location --request DELETE "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
  --header "Authorization: Bearer $env_access_token"