4. Use Integration in Node

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

Now let’s connect the node to the integration so it uses real credentials to call an external API.

Declare the integration dependency

Update the node class to reference the integration:

class GetWeatherNode(BaseNodeV2[GetWeatherConfig, GetWeatherOutputs]):
    node_name = "GetWeatherNode"
    title = "Get Weather"
    description = "Returns weather data for a given city"
    category = NodeCategory.DATA
    color = "#4A90E2"
    integrations = {"weather_api": ["api_key"]}  # integration_type: [required_fields]

    # ... same config schema (with a bindable `city`) and output schema ...

    async def call(self, ctx: RemoteExecutionContext) -> dict:
        # Lazy-import network deps inside call() — a top-level `import httpx`
        # can break manifest generation (see the runtime gotchas in Advanced
        # Techniques).
        import httpx

        from noxus_sdk.errors import IntegrationFailedError

        # Get credentials from the execution context
        creds = ctx.get_integration_credentials("weather_api") or {}
        api_key = creds.get("api_key", "")

        if not api_key:
            raise IntegrationFailedError(
                "No Weather API key connected — add it in Workspace Settings → Integrations."
            )

        # Bindable inputs are read from self.config, just like any config field.
        city = self.config.city

        # Call the real API
        async with httpx.AsyncClient() as client:
            response = await client.get(
                "https://api.openweathermap.org/data/2.5/weather",
                params={"q": city, "appid": api_key, "units": "metric"},
            )
            response.raise_for_status()
            data = response.json()

        return {
            "temperature": f"{data['main']['temp']}°C",
            "description": data["weather"][0]["description"].capitalize(),
        }

integrations works identically on V1 and V2 nodes. This continues the V2 GetWeatherNode from part 2 — its city input is a bindable=True config field, so call(ctx) reads self.config.city rather than taking a city argument. (A V1 node would instead receive city as a keyword argument.)

What changed

integrations = {"weather_api": ["api_key"]} — declares this node depends on the weather_api integration and needs the api_key field. The platform shows a credential picker in the editor and injects the decrypted credentials into ctx for the run.
ctx.get_integration_credentials("weather_api") — retrieves the decrypted credentials at runtime as a plain dict keyed by your BaseCredentials field names. Fall back with or {} and read fields with .get(...) so a missing credential is a clean, actionable failure.
raise IntegrationFailedError(...) — the SDK’s typed error for credential/API problems (noxus_sdk.errors). Prefer it over a bare ValueError: the message crosses the sandbox boundary and becomes the node’s user-visible failure reason (the exception type itself does not cross, so make the message actionable).

How credentials flow

Credentials are never stored in the plugin. They’re decrypted by the platform at execution time and passed through the RemoteExecutionContext for that specific run.

Using multiple integrations

A node can depend on more than one integration:

class CrossPostConfig(NodeConfiguration):
    message: str = Parameter(
        default="", bindable=True, display=ConfigBigText(label="Message"),
    )


class CrossPostOutputs(NodeOutputs):
    status: str


class CrossPostNode(BaseNodeV2[CrossPostConfig, CrossPostOutputs]):
    node_name = "CrossPostNode"
    title = "Cross Post"
    description = "Posts a message to multiple networks"
    integrations = {
        "twitter": ["api_key", "api_secret"],
        "linkedin": ["access_token"],
    }

    async def call(self, ctx: RemoteExecutionContext) -> dict:
        twitter_creds = ctx.get_integration_credentials("twitter") or {}
        linkedin_creds = ctx.get_integration_credentials("linkedin") or {}

        # Use both sets of credentials to post self.config.message ...
        return {"status": "posted"}

A reusable credentials helper

Real plugins wrap credential lookup in a small helper next to the integration, so every node reads the same fields the same way. The Proxy API scraper plugin does exactly this:

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

Error handling for credentials

Always validate that credentials exist before using them, and raise IntegrationFailedError so the message surfaces as the node’s failure reason:

from noxus_sdk.errors import IntegrationFailedError


async def call(self, ctx: RemoteExecutionContext) -> dict:
    creds = ctx.get_integration_credentials("weather_api") or {}

    if not creds.get("api_key"):
        raise IntegrationFailedError(
            "Weather API credentials not configured. "
            "Go to Workspace control → Integrations to add your API key."
        )

    # Safe to use credentials...

Next: Working with Files →

Read and create files from plugin nodes.

Overview

Tutorial

Reference

GitOps

Declare the integration dependency

What changed

How credentials flow

Using multiple integrations

A reusable credentials helper

Error handling for credentials

Next: Working with Files →

​Declare the integration dependency

​What changed

​How credentials flow

​Using multiple integrations

​A reusable credentials helper

​Error handling for credentials

Next: Working with Files →

Declare the integration dependency

What changed

How credentials flow

Using multiple integrations

A reusable credentials helper

Error handling for credentials