Create a custom connector

POST/api/v1/custom-providers

Creates an environment-scoped custom provider (connector) with authentication patterns and optional proxy configuration. The returned identifier must be used for all subsequent update and delete operations on this provider.

This page as markdown Custom connectors overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Body

auth_patternsarray of objectrequired

Authentication patterns for the connected app provider

Show 9 child attributes

display_namestringrequired

Name of the method, shown to the user while they connect.

typestring (enum)required

How users authenticate. Use NO_AUTH only for a public MCP server, with is_mcp set and no fields. The type of an existing pattern can't change.

OAUTHBEARERAPI_KEYBASICNO_AUTH

account_fieldsarray of object

Inputs collected for an OAUTH pattern, such as a value proxy_url needs. Same fields as fields.

auth_field_mutationsobject

A prefix, suffix or default applied to a credential before Scalekit sends it, keyed by api_key, token, username or password.

auth_header_key_overridestring

Header to send the credential in when the app doesn't use Authorization, such as X-API-Key.

descriptionstring

Short explanation of the method.

fieldsarray of object

Inputs the user fills in for BEARER, API_KEY and BASIC. Leave it empty for OAUTH and NO_AUTH.

Show 6 child attributes

field_namestringrequired

Key the value is stored under: token for BEARER, api_key for API_KEY, username and password for BASIC, or a name such as domain that proxy_url uses as {{domain}}.

hintstring

Helper text shown with the input.

input_typestring (enum)

Use password for secrets, so the input is masked.

textpasswordselect

labelstring

Label shown above the input.

optionsarray of object

Choices for a select input, each with value, display_name, description and default.

requiredboolean

Whether the user must fill in the input before connecting.

is_mcpboolean

Set to true when proxy_url is an MCP server. Set it on every pattern; it can't change later.

oauth_configobject

OAuth settings for an OAUTH pattern. For an MCP server, {"pkce_enabled": true} is enough: the server handles authorization.

Show 5 child attributes

authorize_uristring

The app's authorization endpoint.

available_scopesarray of object

Scopes the connection can request, each with scope, display_name, description and required.

pkce_enabledboolean

Whether the authorization flow uses PKCE.

token_uristring

The app's token endpoint.

user_info_uristring

Endpoint that returns the signed-in user.

display_namestringrequired

Display name for the connected app provider

proxy_urlstringrequired

Proxy URL for the connected app provider. Must start with https://

descriptionstring

Description of the connected app provider

icon_srcstring

URL for the provider icon. Should be an SVG image sized 800x800 pixels for best rendering experience.

metadataobject

Custom key-value metadata for this provider. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.

proxy_enabledboolean

This flag indicates whether proxying is turned on for the connected app provider. When enabled, requests are routed through the provider proxy instead of being sent directly.

scalekit_client.actions.providers.create_custom_provider

Create a new custom provider.

scalekit_client.actions.providers.create_custom_provider(
    request: CreateCustomProviderRequest,
) -> CreateCustomProviderResponse

Parameters

requestCreateCustomProviderRequestrequired

Request object containing display_name (required), proxy_url (required), and optional description, proxy_enabled, auth_patterns, icon_src, and metadata.

Returns CreateCustomProviderResponse: The created provider with its server-assigned identifier and all decoded auth_patterns.

From scalekit-sdk-python 2.19.1.

scalekit.actions.providers.createCustomProvider

Creates a custom connector.

scalekit.actions.providers.createCustomProvider(
  params: {
    displayName: string;
    proxyUrl: string;
    proxyEnabled?: boolean;
    description?: string;
    authPatterns: AuthPattern[];
    iconSrc?: string;
    metadata?: Record<string, string>;
  },
): Promise<CreateProviderResponse>

Parameters

displayNamestringrequired

Human-readable name. Letters, digits and spaces only. Suffix it with "MCP" when the connector fronts an MCP server.

proxyUrlstringrequired

Base HTTPS URL of the upstream service.

proxyEnabledboolean

Whether Scalekit proxies requests. Defaults to true.

descriptionstring

Description of the connected app provider

authPatternsAuthPattern[]required

How users authenticate: one pattern, with its type, display_name and the fields users fill in.

iconSrcstring

URL for the provider icon. Should be an SVG image sized 800x800 pixels for best rendering experience.

metadataRecord<string, string>

Custom key-value metadata for this provider. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.

Returns Promise<CreateProviderResponse>: provider.identifier on the response is the id you pass to updateCustomProvider and deleteCustomProvider.

From @scalekit-sdk/node 2.18.0.

Response 200

providerobject

The connector.

Show 14 child attributes

auth_patternsarray of object

How users authenticate, as sent in the request.

Show 9 child attributes

account_fieldsarray of object

Inputs collected for an OAUTH pattern, such as a value proxy_url needs. Same fields as fields.

auth_field_mutationsobject

A prefix, suffix or default applied to a credential before Scalekit sends it, keyed by api_key, token, username or password.

auth_header_key_overridestring

Header to send the credential in when the app doesn't use Authorization, such as X-API-Key.

descriptionstring

Short explanation of the method.

display_namestring

Name of the method, shown to the user while they connect.

fieldsarray of object

Inputs the user fills in for BEARER, API_KEY and BASIC. Leave it empty for OAUTH and NO_AUTH.

Show 6 child attributes

field_namestring

Key the value is stored under: token for BEARER, api_key for API_KEY, username and password for BASIC, or a name such as domain that proxy_url uses as {{domain}}.

hintstring

Helper text shown with the input.

input_typestring (enum)

Use password for secrets, so the input is masked.

textpasswordselect

labelstring

Label shown above the input.

optionsarray of object

Choices for a select input, each with value, display_name, description and default.

requiredboolean

Whether the user must fill in the input before connecting.

is_mcpboolean

Set to true when proxy_url is an MCP server. Set it on every pattern; it can't change later.

oauth_configobject

OAuth settings for an OAUTH pattern. For an MCP server, {"pkce_enabled": true} is enough: the server handles authorization.

Show 5 child attributes

authorize_uristring

The app's authorization endpoint.

available_scopesarray of object

Scopes the connection can request, each with scope, display_name, description and required.

pkce_enabledboolean

Whether the authorization flow uses PKCE.

token_uristring

The app's token endpoint.

user_info_uristring

Endpoint that returns the signed-in user.

typestring (enum)

How users authenticate. Use NO_AUTH only for a public MCP server, with is_mcp set and no fields. The type of an existing pattern can't change.

OAUTHBEARERAPI_KEYBASICNO_AUTH

categoriesarray of string

Catalog categories. Empty for a custom connector.

coming_soonboolean

Whether the catalog lists the connector as coming soon.

descriptionstring

Short description of the app.

display_namestring

Name shown to users.

display_priorityinteger

Where the connector sorts in lists; lower numbers come first.

icon_srcstring

URL of the connector's icon.

idstring

Scalekit's ID for the connector.

identifierstring

Pass it to update and delete the connector. Scalekit derives it from display_name.

is_customboolean

Indicates whether the provider is environment-scoped (custom provider)

is_custom_mcpboolean

Indicates whether this is an environment-scoped MCP-based custom provider

metadataobject

Custom key-value metadata stored for this provider. Returned for all providers; defaults to {} when no metadata has been set.

proxy_enabledboolean

Whether Scalekit proxies requests to proxy_url.

proxy_urlstring

Base URL of the API that the proxy calls.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - the provider payload failed validation (e.g. missing required fields or invalid proxy URL)

Used in

Create a connector

Request

1
curl -sS -X POST \
2
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers" \
3
  -H "Authorization: Bearer $TOKEN" \
4
  -H "Content-Type: application/json" \
5
  -d '{
6
    "display_name": "Example API",
7
    "description": "Connect to an API that accepts a static bearer token",
8
    "auth_patterns": [
9
      {
10
        "type": "BEARER",
11
        "display_name": "Bearer Token",
12
        "description": "Authenticate with a static bearer token",
13
        "fields": [
14
          {
15
            "field_name": "token",
16
            "label": "Bearer Token",
17
            "input_type": "password",
18
            "hint": "Your long-lived bearer token",
19
            "required": true
20
          }
21
        ]
22
      }
23
    ],
24
    "proxy_url": "https://api.example.com",
25
    "proxy_enabled": true
26
  }'

1
from scalekit.actions.types import CreateCustomProviderRequest
2

3
result = scalekit_client.actions.providers.create_custom_provider(
4
    request=CreateCustomProviderRequest(
5
        display_name="Example API",
6
        description="Connect to an API that accepts a static bearer token",
7
        auth_patterns=[
8
            {
9
                "type": "BEARER",
10
                "display_name": "Bearer Token",
11
                "description": "Authenticate with a static bearer token",
12
                "fields": [
13
                    {
14
                        "field_name": "token",
15
                        "label": "Bearer Token",
16
                        "input_type": "password",
17
                        "hint": "Your long-lived bearer token",
18
                        "required": True,
19
                    },
20
                ],
21
            },
22
        ],
23
        proxy_url="https://api.example.com",
24
        proxy_enabled=True,
25
    ),
26
)

1
const result = await scalekit.actions.providers.createCustomProvider({
2
  displayName: "Example API",
3
  proxyUrl: "https://api.example.com",
4
  proxyEnabled: true,
5
  description: "Connect to an API that accepts a static bearer token",
6
  authPatterns: [
7
    {
8
      type: "BEARER",
9
      display_name: "Bearer Token",
10
      description: "Authenticate with a static bearer token",
11
      fields: [
12
        {
13
          field_name: "token",
14
          label: "Bearer Token",
15
          input_type: "password",
16
          hint: "Your long-lived bearer token",
17
          required: true,
18
        },
19
      ],
20
    },
21
  ],
22
});

Response 200

1
{
2
  "provider": {
3
    "id": "prvd_84718296317953812",
4
    "identifier": "EXAMPLEAPI:12345",
5
    "display_name": "Example API",
6
    "description": "Connect to an API that accepts a static bearer token",
7
    "auth_patterns": [
8
      {
9
        "type": "BEARER",
10
        "display_name": "Bearer Token",
11
        "description": "Authenticate with a static bearer token",
12
        "fields": [
13
          {
14
            "field_name": "token",
15
            "label": "Bearer Token",
16
            "input_type": "password",
17
            "hint": "Your long-lived bearer token",
18
            "required": true
19
          }
20
        ]
21
      }
22
    ],
23
    "proxy_url": "https://api.example.com",
24
    "proxy_enabled": true,
25
    "categories": [],
26
    "icon_src": "",
27
    "display_priority": 1,
28
    "coming_soon": false,
29
    "is_custom": true,
30
    "is_custom_mcp": false,
31
    "metadata": {}
32
  }
33
}