External APIs

The plugin runs in an iframe with a strict CSP policy — direct fetch/XMLHttpRequest calls to external services will be blocked by the browser. All outgoing HTTP requests must go through hostApi.externalApiCall(): the plugin passes the request parameters through the bridge, the host executes it on its side, and returns the result.

Manifest permission

Add the permissions.external section to manifest.json with a list of allowed domains:

{
    "permissions": {
        "external": [
            {
                "domain": "api.example.com",
                "authorization": {
                    "type": "oauth",
                    "scopes": ["read", "write"],
                    "contextTypes": ["user"]
                }
            }
        ]
    }
}

The authorization field is optional — you can omit it for domains that don't require authorization.

Basic usage

A typical scenario — check authorization, request it from the user if needed, then call the API:

import {
    hostApi,
    PluginActionError,
    EXTERNAL_API_CALL_ERROR,
} from "@weavix/sdk-react";

async function fetchItems() {
    // Check authorization and show the dialog if needed
    const { success } = await hostApi.externalApiAuthCheckAndRequest({
        domains: ["api.example.com"],
        contextType: "user",
    });
    if (!success) {
        // The user closed the dialog or the timeout expired
        return;
    }

    // Call the external API through the host's proxy
    const { status, body } = await hostApi.externalApiCall({
        url: "https://api.example.com/v1/items",
        method: "GET",
        contextType: "user",
    });
    // status — HTTP response status
    // body   — response body (Record<string, unknown>)
}

POST with a body and timeout:

const { status, body } = await hostApi.externalApiCall({
    url: "https://api.example.com/v1/items",
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: { name: "New item", value: 42 },
    contextType: "organization",
    timeoutMs: 10000,
});

Error handling

On a network error or an error response status, the host throws a PluginActionError with the code EXTERNAL_API_CALL_ERROR (1013). Details are in e.errorData:

try {
    await hostApi.externalApiCall({
        url: "https://api.example.com/data",
        method: "GET",
    });
} catch (e) {
    if (e instanceof PluginActionError && e.code === EXTERNAL_API_CALL_ERROR) {
        console.error("Proxy error:", e.errorData);
    }
}

Managing authorization

The quick way — externalApiAuthCheckAndRequest checks authorization and, if needed, shows the dialog in a single call; see the example above.

Manual control. If you need finer-grained control, use the individual methods:

// Check the status for domains
const { domains } = await hostApi.externalApiAuthGetStatus({
    domains: ["api.example.com"],
    contextType: "user",
});
const isAuthed = domains.every((d) => d.authenticated);

// Show the authorization dialog with a hint
if (!isAuthed) {
    await hostApi.externalApiAuthRequest({
        domains: [
            {
                domain: "api.example.com",
                instructions: {
                    ru: "Войдите в Example",
                    en: "Sign in to Example",
                },
            },
        ],
    });
}

// Revoke saved credentials
await hostApi.externalApiAuthRevoke({
    domains: ["api.example.com"],
    contextType: "user",
});

For more details on the methods, see hostApi.externalApi*.

Was the article helpful?

Working with the Yandex Tracker API

Data storage