Creating Integrations

Integrations are how a plugin authenticates to an external service. An integration is a typed credentials schema plus a small class that describes it; nodes then declare which integration they need and read its credentials at run time. Credentials are the one per-workspace part of the plugin model — each workspace connects its own, and the platform injects them into the node’s execution context.

The three pieces

Declare a credentials schema

A BaseCredentials subclass with a type and one Parameter per field. Mask secrets with ConfigPassword. Override is_ready() to say when the credential is usable.

Declare the integration

A BaseIntegration[YourCredentials] subclass — display_name and image. Optionally override is_ready to probe the service for real.

Bind it on a node

Set integrations = {"<type>": ["<field>", ...]} on the node, and read the injected credentials with ctx.get_integration_credentials("<type>").

Defining credentials and the integration

BaseCredentials and BaseIntegration come from noxus_sdk.integrations.base; the field widgets from noxus_sdk.ncl. The credential’s type string is the id nodes bind to and the key the platform stores credentials under.

from typing import ClassVar
from noxus_sdk.integrations.base import BaseCredentials, BaseIntegration
from noxus_sdk.ncl import ConfigPassword, ConfigText, Parameter

class MyServiceCredentials(BaseCredentials):
    type: ClassVar[str] = "my_service"

    base_url: str = Parameter(
        display=ConfigText(label="API URL", placeholder="https://api.myservice.com"),
    )
    api_key: str = Parameter(
        display=ConfigPassword(label="API Key", placeholder="Your API key"),
    )

    def is_ready(self) -> bool:
        return bool(self.base_url and self.api_key)

class MyServiceIntegration(BaseIntegration[MyServiceCredentials]):
    display_name = "My Service"
    image = "https://.../my-service-logo.png"

The integration’s credential type is derived automatically from the credentials class, and the field widgets render the connect form in workspace settings. Return the integration from your plugin’s integrations():

def integrations(self) -> list[type[BaseIntegration]]:
    return [MyServiceIntegration]

Live readiness checks

BaseIntegration.is_ready defaults to “the fields validate and credentials.is_ready() is true”. Override it (async) to probe the service, so readiness reflects real authorization rather than just filled-in fields — as the ClipOne integration does:

from typing import Any

class ClipOneIntegration(BaseIntegration[ClipOneCredentials]):
    display_name = "ClipOne"
    image = _IMAGE

    @classmethod
    async def is_ready(cls, creds: dict[str, Any] | None) -> bool:
        parsed = cls.get_credentials(creds)
        if parsed is None or not parsed.is_ready():
            return False
        try:
            client = ClipOneClient(api_key=parsed.api_key, url=parsed.url,
                                   pre_auth_header=parsed.pre_auth)
            await client.check_connectivity()
            return True
        except Exception:
            return False

Binding an integration on a node

A node lists the credentials it needs in integrations — a mapping of the credential type to the field names it consumes — and reads them from ctx. The platform shows a credential picker for that type on the node and injects the selected workspace credential into the call.

from noxus_sdk.nodes.base import BaseNode
from noxus_sdk.plugins.context import RemoteExecutionContext

class MyServiceNode(BaseNode[MyServiceConfig]):
    node_name = "MyServiceFetch"
    title = "Fetch from My Service"
    integrations = {"my_service": ["api_key"]}

    async def call(self, ctx: RemoteExecutionContext, path: str) -> dict:
        creds = ctx.get_integration_credentials("my_service")
        api_key = creds.get("api_key", "")
        base_url = creds.get("base_url", "")
        # ... call the external API with httpx, curl_cffi, etc.
        return {"result": "..."}

A common pattern is a tiny helper that builds a client from the context, so every node shares one place that reads the credentials — the scrapers plugin does this for its shared Proxy API key:

def api_key_from_ctx(ctx: RemoteExecutionContext) -> str:
    creds = ctx.get_integration_credentials("proxy_api") or {}
    return creds.get("api_key", "")

Read credentials from ctx at call time — never cache them across calls. They are per-workspace and may differ between runs. If a required credential is missing, raise IntegrationFailedError from noxus_sdk.errors so the user sees an actionable message.

Development Flow

Model the credentials

Decide the fields (URL, key, tenant, …). Mask every secret with ConfigPassword. Implement is_ready() on the credentials.

Build the client layer

A robust async client (e.g. httpx) with retries and typed parsing. Import heavy deps inside call/helpers, not at module top — manifest generation imports your module in a lightweight environment.

Expose nodes

Add nodes that bind the integration via integrations={...} and read ctx.

Probe readiness

Override is_ready to hit the real service so the workspace UI shows accurate connection status.

Security & Isolation

No platform credential enters the sandbox. Only the workspace-scoped integration credentials the node declared are injected, and only for the calling workspace.
Per-workspace boundary. A plugin cannot read another tenant’s credentials or files; the single-use call token scopes every callback to ctx.group_id.

Configurable Plugins

Add plugin-level config, node config, and dynamic config to your integration.

Overview

Tutorial

Reference

GitOps

The three pieces

Defining credentials and the integration

Live readiness checks

Binding an integration on a node

Development Flow

Security & Isolation

Configurable Plugins

​The three pieces

​Defining credentials and the integration

​Live readiness checks

​Binding an integration on a node

​Development Flow

​Security & Isolation

Configurable Plugins

The three pieces

Defining credentials and the integration

Live readiness checks

Binding an integration on a node

Development Flow

Security & Isolation