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 ConfigText, Parameter


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

    api_key: str = Parameter(
        default="",
        title="API Key",
        description="Your weather API key",
        display=ConfigText(),
    )

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


class WeatherAPIIntegration(BaseIntegration[WeatherAPICredentials]):
    type = "weather_api"
    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.)
is_ready() returns True when the credentials are valid enough to use — the UI shows this status
BaseIntegration ties the credentials to a display name and icon that appear in workspace settings
type must match between the credentials class and the integration class — this is the identifier used throughout

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 Settings → 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 for this integration (string)
`display_name`	Human-readable name shown in the UI
`image`	Icon URL for the integration tile
`credentials_class`	Pydantic model (auto-set from the 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

Credential field types

You can use any NCL display type for credential fields:

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

    # Simple text input
    api_key: str = Parameter(
        default="",
        title="API Key",
        display=ConfigText(),
    )

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

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

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

Credential field types

Next: Use Integration in Node →

​Define credentials and integration

​How it works

​Register the integration

​Integration anatomy

​Credential field types

Next: Use Integration in Node →

Define credentials and integration

How it works

Register the integration

Integration anatomy

Credential field types