Connections

Learn how to define connections for your connector. Connections enable your connector to communicate with external systems. Without a connection, your connector can’t perform operations, triggers, or other components. Connector Builder supports creating connectors that integrate with SaaS applications that use HTTP-based connectivity.

Each connection uses an authentication type. An authentication type is a specific method or protocol used to verify and authorize access to the external system. Connector Builder supports these authentication types for connections.

ApiKey

ApiKey authentication connects to applications without explicitly defining a user. You must add this key to all requests, and the cloud application identifies the origin of the request and completes the authorization.
Basic

Basic authentication enables the user to provide a username and password when logging in to an external system.
Bearer

Bearer authentication sends a header named Authorization with a value of Bearer and a token with every request.
OAuth2BrowserFlow

OAuth2BrowserFlow authentication is the authorization code grant type, which is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner’s user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.
OAuth2ClientCredentials

OAuth2ClientCredentials authentication obtains an access token from a user-defined path.

You can define connections using either the UI or LinkWeave. Use the UI as your primary approach, as it significantly reduces manual development effort. Reserve LinkWeave for advanced scenarios that require custom logic. With Connector Builder, the goal is to focus on reviewing and validating the generated process, rather than writing custom code.

Define Connections Using the UI

When you generate base connectivity, if the authentication type specified in the API specification or by AI assistance is supported by Connector Builder, the authentication type and a connection for each endpoint are automatically defined for you.

Define Connections Using LinkWeave

You can define connections using LinkWeave.

Connection Structure
Authentication Types

Connection Structure

In LinkWeave, connections are functions that transform requests into responses:

(ConnectionRequest) -> ConnectionResponse

For HTTP-based connections, this becomes:

(HttpRequester) -> HttpResponse

These types form the structure of connections.

Connection: Connection function
ConnectionProvider: Connection creation and configuration
HTTPConnection: Specialized connection for HTTP requests
HTTPConnectionProvider: HTTP-specific connection provider

Connection

Connection<ConnectionRequest <: Object, ConnectionResponse <: Object> =
  (ConnectionRequest) -> ConnectionResponse

Parameters:

ConnectionRequest: Object sent to the target system
ConnectionResponse: Object returned from the target system

ConnectionProvider

ConnectionProvider<ConnectionType <: Connection, InputType <: Object, AuthenticationType <: Object>

Parameters:

ConnectionType: Connection function itself
InputType: Input parameters required to create the connection
AuthenticationType: Authentication schema

ConnectionProvider returns an object with these properties:

{
  connect: (InputType) -> ConnectionType,
  authenticationType: AuthenticationType,
  validate?: (ConnectionType) -> ConnectionValidationResult
}

Properties:

connect: Creates a connection from input parameters
authenticationType: Defines the authentication schema
validate: (Optional) Tests the connection and returns validation results

HTTPConnection

HttpConnection = Connection<HttpRequester, HttpResponse>

HTTPConnectionProvider

HttpConnectionProvider<InputType <: Object, HttpAuthenticationType> =
  ConnectionProvider<HttpConnection, InputType, HttpAuthenticationType>

HTTPConnectionProvider also supports an optional extensions attribute for customizing connection behavior. Use extensions to add custom headers, query parameters, or other modifications to requests.

extensions?: (InputType) -> Array<ConnectionProviderExtensions | ConnectionProviderOAuthExtensions>

The definitions for these types are:

type ConnectionProviderExtensions = {
  in: "query" | "header" | "body" | "path",
  name: String,
  value: String
}

type ConnectionProviderOAuthExtensions = {
  inDance: true | false,
} & ConnectionProviderExtensions

You can also enhance any authentication type with extensions. This example adds a static header to a Basic authentication type.

@ConnectionElement()
  var basicAuth = defineBasicHttpConnectionProvider<BasicAuthSchema & { baseUri: String }>((schema) -> {
    username: schema.username,
    password: schema.password
  }, (schema) -> {
    baseUri: schema.baseUri
  }),
  (schema) -> [
                  {in: "header", name:"customHeaderStatic", value: "myValue"}
                ] //This extensions attribute is optional

Authentication Types

You can define the connections for authentication types.

ApiKey
Basic
Bearer
OAuth2

ApiKey

@ConnectionElement()
  var apiKeyAuth = defineApiKeyHttpConnectionProvider<ApiKeyAuthSchema & { baseUri: String }>((schema) -> {
    apiKey: schema.apiKey
  }, (schema) -> {
    baseUri: schema.baseUri
  }, {
    in: "header",
    name: "X-ApiKey"
  })

The APIKey connection is defined and created using ApiKeyAuthSchema, which is the input connection type definition and the connection parameters.

The defineApiKeyHttpConnectionProvider function requires these parameters.

schemaMapper

From an input, schemaMapper returns ApiKeyAuthSchema.

type ApiKeyAuthSchema = {|
      apiKey: @SemanticTerms(value = ["apiKey"]) String
  |}

connectionProviderSchemaMapper

From an input, connectionProviderSchemaMapper returns HttpConnectionProviderSchema.
```
type HttpConnectionProviderSchema = {
  baseUri?: String
}
```

attributes

attributes returns ApiKeyAuthAttributesSchema.

type ApiKeyAuthAttributesSchema = {
  in: 'header' | 'cookie' | 'query',
  name: String
}

LinkWeave supports a schema based on a single API key.

Basic

@ConnectionElement()
  var basicAuth = defineBasicHttpConnectionProvider<BasicAuthSchema & { baseUri: String }>((schema) -> {
    username: schema.username,
    password: schema.password
  }, (schema) -> {
    baseUri: schema.baseUri
  })

The Basic connection is defined and created using BasicAuthDefinition, which is the input connection type definition and the connection parameters.

The defineBasicHttpConnectionProvider function requires these parameters.

schemaMapper

From an input, schemaMapper returns BasicAuthSchema.

type BasicAuthSchema = {
  username: @SemanticTerms(value = ["username"]) String,
  password: @SemanticTerms(value = ["password"]) String
}

connectionProviderSchemaMapper

From an input, connectionProviderSchemaMapper returns HttpConnectionProviderSchema.
```
type HttpConnectionProviderSchema = {
  baseUri?: String
}
```

Bearer

@ConnectionElement()
  var bearerAuth = defineBearerHttpConnectionProvider<BearerAuthSchema & { baseUri: String }>((schema) -> {
    token: schema.token
  }, (schema) -> {
    baseUri: schema.baseUri
  })

The Bearer connection is defined and created using BearerAuthSchema, which is the input connection type definition and the connection parameters.

The defineBearerHttpConnectionProvider function requires these parameters.

schemaMapper

From an input, schemaMapper returns BearerAuthSchema.

type BearerAuthSchema = {
  token: @SemanticTerms(value = ["secretToken"]) String
}

connectionProviderSchemaMapper

From an input, connectionProviderSchemaMapper returns HttpConnectionProviderSchema.
```
type HttpConnectionProviderSchema = {
  baseUri?: String
}
```

OAuth2

@ConnectionElement()
type OAuthAuthDefinition = {
       baseUri: String,
       accessToken: @SemanticTerms(value = ["password"]) String
}

var oAuth: defineOAuth2Connection<OAuthAuthDefinition>(
       (parameter) -> {accessToken: parameter.accessToken},
       (parameter) -> {baseUri: parameter.baseUri},
       {
           grantType: 'authorizationCode',
           authorizationUrl: "http://localhost/authorize",
           tokenUrl: "http://localhost/token",
           scopes: ["test"]
       }
     )

The OAuth2 connection is defined and created using OAuthAuthDefinition, which is the input connection type definition and the connection parameters.

The defineOAuth2Connection function requires these parameters.

schemaMapper

From an input, schemaMapper returns OAuth2AuthSchema.

type OAuth2AuthSchema = {|
  accessToken: @SemanticTerms(value = ["password"]) String
|}

connectionSchemaMapper

From an input, connectionSchemaMapper returns HttpConnectionProviderSchema.
```
type HttpConnectionProviderSchema = {|
  baseUri?: String
|}
```

attributes

attributes returns OAuth2Schema.

type OAuth2Schema<OAuthGrantType <: AuthorizationCodeGrantType | ClientCredentialsGrantType | PasswordGrantType | ImplicitGrantType> = OAuthGrantType

OAuth2 supports these grant types.

authorizationCode
clientCredentials

Each grant type has specific configuration requirements. For example, for authorizationCode:

type GrantType = 'authorizationCode' | 'clientCredentials' | 'password' | 'implicit'

type CommonOAuth2GrantTypeSchema<GrantType> = {|
  "grantType": GrantType,
  refreshUrl?: String,
  scopes: Array<String>
|}

type AuthorizationCodeGrantType = CommonOAuth2GrantTypeSchema<'authorizationCode'> & {|
  authorizationUrl: String,
  tokenUrl: String
|}