register-custom-api

Name: Flowstack
Author: Flowstack

recipesince 0.2.8

Let the app OWNER register any HTTPS REST API as an integration the agent can call as a tool

Plane: http_integration · Requires: capability external_integration

Steps: 1. useIntegrations — Owner-side settings UI: create({ name, description, base_url, auth_type, auth_config, endpoints }) — creds are encrypted at rest; the frontend never sees raw secrets after creation. 2. useAgent — With capabilities ['external_integration','data_access'], prompt the agent to call the new integration's endpoints by name and write results into a collection. 3. useCollection — Read that collection reactively for the app UI (refreshOnAgentComplete: true).

Examples

End-to-end example

import { useIntegrations } from '@flowstack/sdk';

export function RegisterShopify() {
  const { integrations, create, isLoading } = useIntegrations();
  if (integrations.some(i => i.name === 'shopify')) return <p>Shopify registered.</p>;

  return (
    <button
      disabled={isLoading}
      onClick={() =>
        create({
          name: 'shopify',
          description: 'Shopify Admin API for order management and reporting',
          base_url: 'https://my-store.myshopify.com/admin/api/2024-01',
          auth_type: 'bearer',
          auth_config: { token: process.env.NEVER_HARDCODE_ME! },
          endpoints: [
            { name: 'list_orders', method: 'GET', path: '/orders.json' },
            { name: 'get_order', method: 'GET', path: '/orders/{id}.json' },
          ],
        })
      }
    >
      Register Shopify
    </button>
  );
}

WarningThis is the OWNER flow (registered once, creds encrypted) — for per-user accounts use the OAuth plane (useConnections) instead.

Warningbase_url must be HTTPS and public; private/internal IPs are rejected (SSRF guard).

WarningCollect the API key via a form field at registration time — never hardcode secrets in app source.

register-custom-api

Examples

See also