Connector SDK (GL Connector SDK)

A Python SDK for seamlessly connecting to APIs that implement Connector's Plugin Architecture under HTTP Interface. This connector acts as a proxy, simplifying the integration with Connector-compatible APIs.

Migration Notice (BOSA → GL Connectors)

This SDK has been renamed from BOSA to GL Connectors. All classes and methods have been updated with backwards-compatible aliases:

Old Name	New Name
BosaConnector	GLConnectors
BosaAuthenticator	GLAuthenticator
BosaConnectorModule	GLConnectorModule
BosaConnectorError	GLConnectorError
BOSAConnectorToolGenerator	GLConnectorToolGenerator
BosaToken	GLToken
BosaUser	GLUser
create_bosa_user()	create_user()
authenticate_bosa_user()	authenticate()

Default API URL: Changed from https://api.bosa.id to https://connector.gdplabs.id

The old names are still available but marked as deprecated. You will see deprecation warnings when using them. Please migrate to the new names to avoid issues in future versions.

Features

• Simple and intuitive API for connecting to Connector-compatible services
• Automatic endpoint discovery and schema validation
• Built-in authentication support (Connector Key and User Token)
• User management and OAuth2 integration flow support
• Type-safe parameter validation
• Flexible parameter passing (dictionary or keyword arguments)
• Retry support for requests that fail (429 or 5xx)
• Response fields filtering based on action and output
• Catalog discovery: list available tools, MCP servers, and curated skills, plus semantic search across all of them
• Tenant skills: list and fetch your tenant's own Agent Skills with a user token, and download/install them to disk

Prerequisites

After the gl-connectors is ready, you can perform the following tasks:

• Ensure Connector is running. If you want to test locally, or you can use Staging or Production environments.
• Create Client
  • You can send a create-client request to the gl-connectors using Postman with the following header and body:
    • Header
      • x-api-key: KEY1
    • Body
      • name: "{client name}"
  • Response :

    {
      "data": {
        "id": "{client_id}",
        "name": "admin",
        "api_key": "{client_api_key}",
        "is_active": true
      },
      "meta": null
    }
    

• Register the user, see the details here.

Installation

Prerequisites

• Python 3.11+ - Install here
• Pip (if using Pip) - Install here
• Poetry 2.1.3+ (if using Poetry) - Install here
• Git (if using Git) - Install here
• For git installation:
  • Access to the GDP Labs SDK github repository

1. Installation from Pypi

Choose one of the following methods to install the package:

Using pip

pip install gl-connectors-sdk

Using Poetry

poetry add gl-connectors-sdk

Using uv (recommended)

uv add gl-connectors-sdk

2. Development Installation (Git)

For development purposes, you can install directly from the Git repository:

poetry add "git+ssh://git@github.com/GDP-ADMIN/bosa-sdk.git#subdirectory=python/gl-connectors-sdk"

Quick Start

Here's a simple example of how to use the GL Connector SDK with API key authentication and user token.

Initialization

Before using the connector, you need to initialize it with your Connector base URL and API key.

from gl_connectors_sdk import GLConnectors

# Initialize the connector
connector = GLConnectors(api_base_url="https://connector.gdplabs.id", api_key="YOUR_API_KEY")

Authentication

After initializing the connector, you can authenticate with your Connector key.

# User token from authentication
user_token = "Enter your key (bearer token) here from authentication, or refer to User Authentication section below"

# Check if a user has an integration for a connector
has_integration = connector.user_has_integration("github", user_token)

if not has_integration:
    # Initiate the OAuth2 flow for a connector
    auth_url = connector.initiate_connector_auth("github", user_token, "https://your-callback-uri.com")
    # Redirect the user to auth_url to complete authentication, we exit here.
    print("Integration with GitHub not found.")
    print(f"Please visit {auth_url} to complete authentication.")
    exit()

Alternatively, you can authenticate the user first and then use their token:

user = connector.authenticate("username", "password")

# Get user token
user_token = user.token

Basic Example (Direct Execution)

It is the basic way to execute actions, where you need to provide the connector name, action name, and user token. The response will contain the data and status:

# Prepare input parameters
params = {
    "repo": "my-local-repo", # try to use your local repo for testing
    "owner": "rexywjy",
}

# Execute the action with user token
data, status = connector.execute("github", "list_collaborators", token=user_token, max_attempts=1, input_=params)
print(data)
print(status)

More details about parameters and actions in gl-connector docs {domain}/docs

Async Usage (Non-Blocking)

Every HTTP-calling method has an async sibling prefixed with a (aexecute, arun, aget_user_info, auser_has_integration, etc.). Async paths use a long-lived httpx.AsyncClient per instance and do not block the event loop. Use async with GLConnectors(...) to ensure all owned clients (authenticator, integration helper, per-module modules) are properly closed.

import asyncio
from gl_connectors_sdk import GLConnectors

async def main():
    async with GLConnectors(api_base_url="https://connector.gdplabs.id", api_key="YOUR_API_KEY") as connector:
        params = {"repo": "my-local-repo", "owner": "rexywjy"}
        data, status = await connector.aexecute(
            "github", "list_collaborators", token=user_token, max_attempts=3, input_=params
        )
        print(data, status)

        # Concurrent calls share the same connection pool — no extra overhead
        results = await asyncio.gather(
            connector.aexecute("github", "list_pull_requests", token=user_token, input_={"owner": "x", "repo": "y"}),
            connector.aexecute("github", "list_issues", token=user_token, input_={"owner": "x", "repo": "y"}),
        )

asyncio.run(main())

Notes:

• Sync methods raise requests.HTTPError / requests.RequestException (preserved for backward compatibility).
• Async methods raise httpx.HTTPStatusError / httpx.RequestError natively.
• The deprecated account parameter is supported on sync methods but has been dropped from async methods — use identifier instead.

Alternative Approach (Fluent Interface)

For more complex scenarios or more control over the execution, you can use the fluent interface. We're recommending this approach if you:

• Need to execute multiple actions with different parameters
• Expecting list response
• Need to execute actions in a loop

# Prepare input parameters
params = {
    "owner": "gdp-admin",
    "author": "samuellusandi",
    "per_page": 1,
    "sort": "author_date",
    "created_date_start": "2025-02-01",
    "created_date_end": "2025-02-02"
}

# Create a connector instance to a service
github = connector.connect('github')

# Execute actions with fluent interface
response = github.action('list_pull_requests')\
    .params(params)\
    .max_attempts(3)\
    .token('user-token')\
    .run()  # Execute and return ActionResponse for advanced data handling

# Get initial data
initial_data = response.get_data()

# Iterate the following next pages
while response.has_next():
    response = response.next_page()
    data = response.get_data()
    # Process data here
    ...

# You can also navigate backwards
while response.has_prev():
    response = response.prev_page()
    data = response.get_data()
    # Process data here
    ...

# Execute multiple independent actions using the same connector instance
commits_response = github.action('list_commits')\
    .params({
        'owner': 'GDP-ADMIN',
        'repo': 'gl-connectors',
        'page': 1,
        'per_page': 10
    })\
    .token('user-token')\
    .run()

run method also available for direct execution from connector instance, without using fluent interface.

# Prepare input parameters
params = {
    "owner": "gdp-admin",
    "author": "samuellusandi",
    "per_page": 1,
    "sort": "author_date",
    "created_date_start": "2025-02-01",
    "created_date_end": "2025-02-02"
}

# Execute actions with run method
response = connector.run('github', 'list_pull_requests', input_=params)
print(response.get_data())

Working with Files using ConnectorFile

When working with APIs that require file uploads or return file downloads, use the ConnectorFile model:

from gl_connectors_sdk.models.file import ConnectorFile

# For uploads: Create a ConnectorFile object
with open("document.pdf", "rb") as f:
    upload_file = ConnectorFile(
        file=f.read(),
        filename="document.pdf",
        content_type="application/pdf"
    )

params = {
  "file": upload_file,
  "name": "My Document"
}

# Include in your parameters
result, status = connector.execute("google_drive", "upload_file", input_=params)

# For downloads: Check response type
file_result, status = connector.execute("google_drive", "download_file", input_={"file_id": "123"})
if isinstance(file_result, ConnectorFile):
    # Save to disk
    with open(file_result.filename or "downloaded_file", "wb") as f:
        f.write(file_result.file)

Discovering Connectors (Catalog)

The SDK exposes the GL Connectors Catalog so you can discover what the backend offers — internal tools, MCP servers, and curated skills — and turn any entry into something usable. All catalog methods are available directly on the GLConnectors instance (each also has an async sibling prefixed with a).

Listing what's available

The three listing methods require no user token and support filtering and pagination (limit defaults to 50, offset to 0):

# List internal tools, optionally filtered by substring, connector, or category
tools = connector.list_tools(q="pull request", connector="github")
for tool in tools.items:
    print(tool.name, "-", tool.description)
print(f"{tools.meta.total} tools total")

# List internal connectors exposed as MCP servers
mcps = connector.list_mcps(category="dev")

# List curated skills (source: 'agent' or 'openclaw')
skills = connector.list_skills(source="agent")

Semantic search

When you don't know the exact name, semantic_search finds the most relevant tools, MCP servers, and skills for a natural-language query. It requires a user token (the query is embedded, which is a billable call):

results = connector.semantic_search("create a pull request", user_token)
print(results.tools)   # Top matching tools
print(results.mcp)     # Top matching MCP servers
print(results.skills)  # Top matching skills

# Restrict to specific kinds and limit results per kind
results = connector.semantic_search("summarize a document", user_token, kinds="tools,skills", count=3)

Making a catalog entry usable

Each catalog entry kind has a "last mile" helper that turns it into something you can run or connect to:

# Tool: build the runnable generated tool a catalog item refers to ("langchain" or "gllm")
item = connector.list_tools(q="list_pull_requests").items[0]
tool = connector.build_catalog_tool(item, tool_type="langchain")

# MCP: produce a ready-to-connect config with the Authorization header populated
mcp_item = connector.list_mcps(q="github").items[0]
mcp_config = connector.get_mcp_config(mcp_item, token=user_token)
print(mcp_config.url, mcp_config.headers)

# Skill: resolve where a curated skill is published, then fetch it yourself
skill_item = connector.list_skills(q="code-review").items[0]
kind, source = connector.catalog.resolve_skill_install_target(skill_item)
print(kind, source)  # e.g. ("github", "anthropics/skills")

Catalog method reference

Method	Async sibling	Auth	Description
list_tools(q, connector, category, limit, offset)	alist_tools	None	List internal tools from the catalog
list_mcps(q, category, limit, offset)	alist_mcps	None	List internal connectors as MCP servers
list_skills(q, source, limit, offset)	alist_skills	None	List curated agent/OpenClaw skills
semantic_search(q, token, kinds, count)	asemantic_search	User token	Semantic search across tools/MCP/skills
build_catalog_tool(item, tool_type)	abuild_catalog_tool	API key	Build the runnable tool for a catalog tool item
get_mcp_config(item, token)	—	—	Build a ready-to-connect MCP config

Notes:

• The lower-level helper is also available as connector.catalog (a GLCatalogHelper), which exposes the same operations plus resolve_skill_install_target(item) — it returns the (kind, source) a catalog skill is published under (("github", "owner/repo") / ("clawhub", "slug-or-url")).
• Listing responses are typed Pydantic models (CatalogToolList, CatalogMcpList, CatalogSkillList) with an items list and pagination meta; search returns a CatalogSearchResponse with tools, mcp, and skills groups.
• Catalog skills are listings, not downloads. The catalog is a directory of third-party skills; the SDK resolves where one lives and leaves fetching to you. Only your tenant's own skills are downloadable through the SDK — see Tenant Skills below, where every artifact comes from a presigned URL.

Tenant Skills (Manage & Download)

Beyond the read-only catalog, a tenant can have its own Agent Skills stored in GL Connectors. The SDK exposes the user-facing read side of that API (/api/skills): list your tenant's skills, fetch one skill's detail, and download/install a skill to disk. These methods authenticate with a user token — the tenant is taken from the token's claims (the SDK never sends X-API-Key on these calls). Each method has an async sibling prefixed with a.

Catalog skills vs. tenant skills. list_skills (catalog) browses the curated, read-only /catalog/skills. The methods below (list_tenant_skills, …) are your tenant's own managed skills under /api/skills. The tenant_ prefix keeps the two from colliding.

Listing and fetching

user_token = connector.authenticate("username", "secret").token

# List your tenant's skills (summaries + pagination meta; limit defaults to 50, offset to 0)
skills = connector.list_tenant_skills(user_token)
for s in skills.items:
    print(s.id, s.source_type, s.name)      # source_type: upload_md | upload_zip | manual | github

# meta is an open object on this endpoint: it, and each of total/limit/offset, may be absent.
# None means "not reported" — not zero — so check before paginating or doing arithmetic on it.
total = skills.meta.total if skills.meta else None
print(f"{total if total is not None else 'unknown'} skills total")

# Fetch one skill's full detail (decrypted frontmatter + a presigned download_url)
detail = connector.get_tenant_skill(user_token, skills.items[0].id)
print(detail.frontmatter)    # dict (github skills are server-side snapshots and carry it too)
print(detail.download_url)   # presigned URL; None only for a github skill pending its first refresh

Downloading a skill

download_tenant_skill takes a skill detail (from get_tenant_skill) and one or more destination directories. Every skill downloads from its presigned download_url — github skills are zip snapshots taken server-side, so the SDK never contacts GitHub and never needs a GitHub token:

source_type	Behaviour	Returned path
upload_zip / github	Fetch the artifact and unzip into its own <dest>/<skill-name>/ parent (path-traversal guarded); create_parent=False extracts directly into <dest>	<dest>/<skill-name> (or <dest>)
upload_md / manual	Fetch the artifact and write <dest>/<skill-name>/SKILL.md	<dest>/<skill-name>

Any other source_type — a format a newer server introduced — raises GLSkillsError instead of being guessed onto disk; upgrade the SDK to install it.

A github skill whose download_url is None predates snapshots: a tenant admin must refresh it once (POST /api/skills/{skill_id}/refresh or the console Refresh button) before it can be downloaded. The same refresh re-syncs a snapshot after the upstream repo changes.

Integrity. When the detail carries a content_sha256, the fetched artifact is verified against it before anything is written to disk, and a mismatch raises GLSkillsError. The digest covers everything the stored artifact carries: a zip is hashed over its whole tree (so a changed supporting file moves the digest too), a single-file artifact over its SKILL.md text. Neither is a hash of the raw archive bytes, which vary between re-archivings of an identical tree.

detail = connector.get_tenant_skill(user_token, skill_id)

# One call handles every source_type:
installed_paths = connector.download_tenant_skill(detail, ["./skills"])

# Overwrite existing files and/or set a custom folder name:
connector.download_tenant_skill(detail, ["./skills"], overwrite=True, name="my-skill")

# Zip artifacts (upload_zip/github): extract the bundle's files straight into ./skills (no <skill-name>/ parent):
connector.download_tenant_skill(detail, ["./skills"], create_parent=False)

# Install into several directories at once. Every destination is checked (path containment,
# clobbering) before the first one is written, so a collision on ./team-b does not leave
# ./team-a half-installed.
connector.download_tenant_skill(detail, ["./team-a/skills", "./team-b/skills"])

Async (use async with so owned clients close cleanly):

async with GLConnectors(api_base_url="https://connector.gdplabs.id", api_key="YOUR_API_KEY") as connector:
    skills = await connector.alist_tenant_skills(user_token)
    detail = await connector.aget_tenant_skill(user_token, skills.items[0].id)
    await connector.adownload_tenant_skill(detail, ["./skills"])

Tenant-skill method reference

Method	Async sibling	Auth	Description
list_tenant_skills(token, limit, offset)	alist_tenant_skills	User token	List the tenant's skills (summaries + meta)
get_tenant_skill(token, skill_id)	aget_tenant_skill	User token	Fetch one skill's detail (frontmatter + presigned download_url)
download_tenant_skill(skill, destination, *, overwrite, name, create_parent)	adownload_tenant_skill	None (presigned URL)	Download a skill to disk by source_type

Notes:

• The lower-level helper is also available as connector.skills (a GLSkillsHelper) with the clean method names list_skills / get_skill / download_skill.
• Listing responses are typed Pydantic models (ManagedSkillList with ManagedSkillSummary items + meta); get_* returns a ManagedSkillDetail.
• download_tenant_skill is a sync wrapper over asyncio.run; call adownload_tenant_skill when already inside an event loop. The presigned download_url is self-authenticating, so no token is needed to fetch it.
• Creating/uploading, updating, or deleting skills is not part of this SDK — those are master-key-gated server operations (POST/PUT/DELETE /api/skills). Skills are created via the API or the master-key console; once they exist, any of the tenant's users can list/get/download them with the methods above.

Available Methods

Connector Instance Methods

The connector instance provides several methods for configuring and executing actions:

• connect(name): Create a connector instance to a service

• action(name): Specify the action to execute

• params(dict): Set request parameters (including pagination parameters like page and per_page). Note that params for each plugin and action could be different

• token(str): Set the user token

• headers(dict): Set custom request headers

• max_attempts(number): Set the maximum number of retry attempts (default: 1) Execution Methods:

• run(): Execute and return ActionResponse for advanced data handling

• execute(): Execute and return data and status for basic data handling. The data part of the return value can be a ConnectorFile object when the API returns a non-JSON response (such as a file download).

Response Handling (ActionResponse)

The ActionResponse class provides methods for handling the response and pagination:

• get_data(): Get the current page data (returns the data field from the response). This can return a ConnectorFile object when the API returns a non-JSON response (such as a file download).
• get_meta(): Get the metadata information from the response (e.g., pagination details, total count)
• get_status(): Get the HTTP status code
• is_list(): Check if response is a list
• has_next(): Check if there is a next page
• has_prev(): Check if there is a previous page
• next_page(): Move to and execute next page
• prev_page(): Move to and execute previous page
• get_all_items(): Get all items from all pages (returns a list of objects containing data and meta for each page)

Data Models

The SDK uses the following data models:

• ActionResponseData: Contains the response data structure with data (list, object, or ConnectorFile instance) and meta (metadata) fields
• InitialExecutorRequest: Stores the initial request parameters used for pagination and subsequent requests
• ConnectorFile: Represents a file in requests and responses with these properties:
  • file: Raw bytes content of the file
  • filename: Optional name of the file
  • content_type: Optional MIME type of the file
  • headers: Optional HTTP headers for the file

Configuration Parameters

• api_base_url: The base URL of your GL Connectors endpoint (default: "https://connector.gdplabs.id"). This parameter is extremely important as it determines the URL of the Connector you are connecting to, and it will be used to populate the available actions/endpoints and their parameters upon initialization.
• api_key: Your Connector key for authentication. This is different from plugin-specific API keys, which are managed separately by the GL Connectors system.

Execution Parameters

• connector: The name of the connector to use. This parameter is used to determine the connector's available actions and their parameters.
• action: The name of the action to execute. This parameter is automatically populated by the connector based on the available actions and their parameters. The list of available actions per connector can be found in https://connector.gdplabs.id/docs and are populated through https://connector.gdplabs.id/connectors.
• max_attempts: The maximum number of attempts to make the API request. If the request fails, the connector will retry the request up to this number of times. The default value is 1 if not provided.
  • The retries are handled automatically by the connector, with exponential backoff.
  • The retries are only done for errors that are considered retryable (429 or 5xx).
• input_: The input parameters for the action. This parameter is a dictionary that contains the parameters for the action. The connector will validate the input parameters against the action's schema.
  • To filter response fields, simply add the response_fields parameter to the input dictionary. This parameter is a list of field names that will be returned in the response. For nested fields, you can use dot notation, e.g. user.login will return the following:

  {
    "user": {
      "login": "userlogin"
    }
  }
  

• token: Optional User Token for authenticating requests. When provided, the connector will include this token in the request headers. This is required for user-specific actions or when working with third-party integrations.

How It Works

1. Initialization: When you create a GLConnectors instance, and trigger an execute(), the connector will first populate and cache the available actions and their parameters. This is done automatically.

2. Action Discovery: The connector expects the Connector to expose an endpoint that lists all available actions and their parameters. This is handled automatically by GL Connectors' HTTP Handler.

3. Execution: When you call execute(), the connector:

   • Validates your input parameters against the action's schema
   • Handles authentication
   • Makes the API request
   • Returns the formatted response

Compatibility

While primarily tested with GL Connectors' HTTP Interface, this connector should theoretically work with any API that implements the Connector's Plugin Architecture, as long as it:

1. Exposes an endpoint listing available actions and their parameters
2. Follows GL Connectors' standard HTTP Interface specifications (through the Plugin Architecture)
   • All actions must be exposed as POST endpoints.
3. Implements the required authentication mechanisms

Error Handling

The connector includes built-in error handling for:

• Invalid parameters
• Authentication failures
• Connection issues
• API response errors

User Authentication

The GL Connector SDK supports user-based authentication which allows for user-specific actions and third-party integrations:

# Step 1: Create a new user
user_data = connector.create_user("username")
# Save the secret for later use
user_secret = user_data.secret

# Step 2: Authenticate the user and obtain their token
token = connector.authenticate("username", user_secret)

# Step 3: Retrieve user information using the obtained token
user_info = connector.get_user_info(token.token)

❗ Important Notes

🛡️ Best Practice: Since bearer tokens can have a long lifespan, it is highly recommended to reuse existing tokens whenever possible. While creating new tokens is functionally acceptable, be aware that older tokens may become dangling and can pose a security risk if they are exposed or misused.

⚠️ Security Reminder: When you register a new user, you will receive a token that starts with "sk-user-...". It is essential to keep this token safe, as it cannot be recovered if lost, and currently, there is no option to reset it.

Integration Management

The GL Connector SDK provides methods to manage third-party integrations for authenticated users:

# Initiate the OAuth2 flow for a connector
auth_url = connector.initiate_connector_auth("github", user_token, "https://your-callback-uri.com")
# Redirect the user to auth_url to complete authentication

# Check if a user has an integration for a connector
has_integration = connector.user_has_integration("github", user_token)

# Retrieve all user integrations information
user_info = connector.get_user_info(user_token)
integrations = user_info.integrations

# Select an integration
select_result = connector.select_integration("github", user_token, integrations[0].user_identifier)

# Remove an integration
remove_result = connector.remove_integration("github", user_token, integrations[0].user_identifier)

References

Product Requirements Documents(PRD):

• GL Connector SDK - Product Document

Architecture Documents:

• GL Connector SDK - Architecture Document

Design Documents:

• GL Connector SDK - Design Document

Implementation Documents:

• GL Connector SDK - Implementation Document