3. First Integration

This is part 3 of the Your First Plugin tutorial. Make sure you’ve completed 2. First Node first.

Integrations handle authentication with external services. When your node needs to talk to an API that requires credentials, you define an integration so users can configure their keys securely in the Noxus UI.

Define credentials and integration

Add to weather_plugin/__init__.py:

from typing import ClassVar

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


class WeatherAPICredentials(BaseCredentials):
    type: ClassVar[str] = "weather_api"

    api_key: str = Parameter(
        default="",
        description="Your weather API key",
        display=ConfigPassword(label="API Key", placeholder="Your OpenWeatherMap key"),
    )

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


class WeatherAPIIntegration(BaseIntegration[WeatherAPICredentials]):
    display_name = "Weather API"
    image = "https://cdn-icons-png.flaticon.com/512/1779/1779940.png"

How it works

BaseCredentials is a Pydantic model that defines the fields users fill in (API keys, tokens, URLs, etc.). It carries a type: ClassVar[str] — the stable identifier used throughout the platform.
is_ready() returns True when the credentials are valid enough to use — the UI shows this status.
BaseIntegration[WeatherAPICredentials] ties the credentials to a display name and icon that appear in workspace control. You do not set type on the integration — the SDK derives it from the credentials class’s type automatically (BaseIntegration.__init_subclass__), so the two can never drift apart.

Every NCL display widget needs a label (ConfigPassword(label="API Key")). It has no default — a bare ConfigText() fails validation. Use ConfigPassword for secrets so the value is masked in the UI (see ClipOne / Proxy API plugins).

Register the integration

Update the plugin class:

class WeatherPlugin(BasePlugin[WeatherPluginConfig]):
    # ... same metadata ...

    def nodes(self):
        return [GetWeatherNode]

    def integrations(self):
        return [WeatherAPIIntegration]

When the plugin is installed, this integration will appear in Workspace control → Integrations where users can enter their API key. Credentials are encrypted and stored by the platform — your plugin code never stores them.

Integration anatomy

Component	Purpose
`type`	Unique identifier — declared on the credentials class as `type: ClassVar[str]`; the integration inherits it automatically
`display_name`	Human-readable name shown in the UI
`image`	Icon URL for the integration tile
`credentials_class`	Pydantic model (auto-set from the `BaseIntegration[...]` generic parameter)
`is_ready()`	Validation — returns `True` when credentials are usable
`scopes`	Optional list of permission scopes (for OAuth-style integrations)
`properties`	Optional dict of extra metadata

Probing readiness against the live API

BaseCredentials.is_ready() only checks that fields are filled in. To make the “connected” status reflect real authorization, override the integration’s is_ready classmethod and probe the API — this is what the ClipOne plugin does:

class WeatherAPIIntegration(BaseIntegration[WeatherAPICredentials]):
    display_name = "Weather API"
    image = "https://cdn-icons-png.flaticon.com/512/1779/1779940.png"

    @classmethod
    async def is_ready(cls, creds: dict | None) -> bool:
        parsed = cls.get_credentials(creds)
        if parsed is None or not parsed.is_ready():
            return False
        # Import heavy/network deps lazily — not at module top (see the runtime
        # gotchas in Advanced Techniques).
        import httpx

        try:
            async with httpx.AsyncClient() as client:
                r = await client.get(
                    "https://api.openweathermap.org/data/2.5/weather",
                    params={"q": "London", "appid": parsed.api_key},
                )
            return r.status_code == 200
        except Exception:
            return False

Credential field types

You can use any NCL display type for credential fields — every widget takes a label, and secrets should use ConfigPassword so they render masked:

from noxus_sdk.ncl import ConfigPassword, ConfigSelect, ConfigText, ConfigToggle, Parameter


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

    # Masked secret input (use ConfigPassword for keys/tokens)
    api_key: str = Parameter(
        default="",
        display=ConfigPassword(label="API Key"),
    )

    # Plain text (e.g. a base URL)
    base_url: str = Parameter(
        default="",
        display=ConfigText(label="Base URL", placeholder="https://api.example.com"),
    )

    # Dropdown select
    region: str = Parameter(
        default="us-east-1",
        display=ConfigSelect(label="Region", values=["us-east-1", "eu-west-1", "ap-southeast-1"]),
    )

    # Toggle
    use_sandbox: bool = Parameter(
        default=False,
        display=ConfigToggle(label="Use Sandbox"),
    )

Next: Use Integration in Node →

Wire the integration into your node to call a real API with credentials.

Overview

Tutorial

Reference

GitOps

Define credentials and integration

How it works

Register the integration

Integration anatomy

Probing readiness against the live API

Credential field types

Next: Use Integration in Node →

​Define credentials and integration

​How it works

​Register the integration

​Integration anatomy

​Probing readiness against the live API

​Credential field types

Next: Use Integration in Node →

Define credentials and integration

How it works

Register the integration

Integration anatomy

Probing readiness against the live API

Credential field types