> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/~/revisions/aj5eaS57qHvafrgYtfbL/fastn-v2/getting-started/key-concepts-and-terminology.md). # Key Concepts & Terminology This page defines the core terms used throughout Fastn's platform and documentation. If you encounter an unfamiliar term while reading other pages, come back here. ### Tenant Model Fastn is a multi-tenant platform. Every entity in the system i.e. connectors, flows, credentials, execution logs is scoped to a specific tenant. The platform has a three-tier hierarchy: #### SaaS Admin You, the SaaS company operator. You have an **organization** in Fastn that represents your company. Within your organization, you configure connectors, build flows, design widgets, and manage your customers (tenants). You access the Fastn dashboard at `live.fastn.ai`. #### End User (Tenant) Your customer. Each tenant gets an isolated environment with their own credentials, integrations, data, and execution history. Tenants interact with Fastn through the **widget** you embed in your product — they never see the Fastn dashboard. #### Platform Admin An internal Fastn role. Platform Admins manage the platform infrastructure, partner onboarding, and global configuration. You'll see this role referenced in the RBAC and API documentation, but it's not something you interact with as a SaaS partner. #### Tenant Isolation Fastn enforces isolation at the database level using Row-Level Security (RLS). A tenant's data is invisible to other tenants. This isn't just application-level filtering — it's enforced by PostgreSQL policies on every query. > **Diagram needed:** Simple visual showing the tenant isolation model — your organization at the top, two or three tenants below, each with their own credentials, data, and executions in separate boxes. Show the RLS boundary. ### Projects and Spaces When you create an account on Fastn, you get a **project** (also called a **space**). A project is your workspace. Everything you build — connectors, flows, widgets, credentials — lives inside your project. Your project has: * A **Project ID** (also called Space ID) — used in API calls and widget embedding * An **API key** — for authenticating API requests to your flows * **Environments** — separate configurations for development, staging, and production ### Connectors A connector is a pre-built integration with a third-party app. Fastn provides connectors for apps like Shopify, Stripe, Xero, QuickBooks, Slack, HubSpot, GitHub, and others. Each connector defines: * **Authentication method** — OAuth2, API Key, Basic Auth, or Custom * **Actions** — things you can do (create a contact, fetch orders, send a message) * **Triggers** — events you can listen for (new order created, invoice updated) * **Entities** — data types the connector works with (contacts, products, orders) #### Credentials The authentication details for a specific connector, scoped to a tenant. When your end user connects their Slack workspace through the widget, Fastn stores their OAuth tokens as credentials. Each tenant has their own credentials — isolated from all other tenants. > **Screenshot needed:** Connectors page in the dashboard showing a list of connected apps (e.g., Slack, Shopify) with their auth type and status. ### Flows A flow is an automated workflow. It defines a trigger (what starts it) and a sequence of steps (what it does). #### Trigger What starts a flow. Five trigger types exist on the platform: | Trigger | What it does | | -------------------- | --------------------------------------------------------------------------------------------------- | | **On API Request** | Flow runs when an HTTP request hits its endpoint. You get a unique URL per flow. | | **On App Event** | Flow runs when something happens in a connected app (new order in Shopify, new contact in HubSpot). | | **On Webhook Event** | Flow runs when an external system sends a webhook to a registered URL. | | **On Schedule** | Flow runs at a set interval (every 15 minutes, daily at 6 AM) or at a specific date/time. | | **On Chat Message** | Flow runs when a message is received through Fastn's AI chat interface. | \ #### Steps The actions a flow performs after the trigger fires. Steps are the building blocks you add to the flow canvas. They're organized into five categories in the step picker: | Category | Components | | ------------------ | ---------------------------------------------------------- | | **Connection** | Connector, Database, File Transport Protocol | | **AI** | AI Agent, AI Action | | **Transformation** | Filter, Limit, Split, Aggregate, Merge, Data Mapper | | **Control** | Custom Code, Switch, Loop, Logger, Log Metrics | | **Trigger** | The trigger step (already placed when you create the flow) | > **Screenshot needed:** Step picker panel in the flow editor showing the 5 tabs (Trigger, Connection, AI, Transformation, Control) with one tab expanded to show its components. #### Flow Status A flow has two states: * **Live** — deployed and actively processing triggers * **Changes Pending** — edits have been made in the editor but not yet deployed You must click **Deploy** in the flow editor toolbar for changes to take effect. Testing a flow (via the **Test** button) does not deploy it. > **📷 Screenshot needed:** Flow editor toolbar showing the Deploy button, Test button, and the status badge (Live vs Changes Pending). #### Execution A single run of a flow. Every time a trigger fires and the flow processes, that's one execution. Executions are logged with status (success, failed, running), duration, HTTP status code, and tenant ID. You view executions in the **Logs** section of the dashboard. > **📷 Screenshot needed:** Logs page showing execution list with columns: Flow Name, Request Time, Duration, HTTP Status Code, Tenant ID. ### Canonical Data Model (CDM) The CDM is Fastn's universal data format. It defines standard entitie such as Contact, Product, Order, Invoice, Inventory Level, Fulfillment with consistent field names and types. When data moves between connectors, Fastn maps it through the CDM. A "customer" object from Shopify gets normalized into a `CDMContact`. That same `CDMContact` can be written to HubSpot as a "contact" or to Xero as a "client." The CDM handles the translation so you don't write custom mappings for every connector pair. ### Widgets Widgets are the UI components you embed in your product for your end users. They're the customer-facing side of Fastn. #### Widget Types * **Selection Flow** — Presents a list of available integrations. Your end users pick which apps they want to connect. * **Configuration Flow** — Collects configuration from your end users during integration setup (field mappings, sync preferences, scheduling options). * **Widgets Starter** — A pre-built integration hub template with connect/disconnect functionality, status display, and activity logs. #### Widget Editor The tool in the Fastn dashboard where you design your widgets. You add screens, configure actions, link flows, and set branding. Widgets are embedded in your product using a JavaScript snippet with your Project ID. > **Screenshot needed:** Widget editor showing the design canvas with screens, the Actions section, and branding options. ### Configurations Key-value pairs that store environment variables and settings for your project. Accessed via **Settings → Configurations** in the dashboard. Configurations follow a 5-level hierarchy — values set at a more specific level override broader defaults: 1. **Flow** (highest priority) — settings specific to one flow 2. **Integration** — settings for a connector integration 3. **Tenant** — settings for a specific end user 4. **Organization** (SaaS) — your company-wide defaults 5. **Platform** (lowest priority) — Fastn global defaults #### Configuration Flows A specific type of flow used to collect and apply configuration from your end users. Configuration Flows are structurally different from regular flows — the only available component is "Configuration Step." You link a Configuration Flow to a widget in the **widget editor's Actions section** (not in Settings → Configurations, which is a separate key-value manager). > **Common confusion:** Settings → Configurations is for environment variables. Linking a configuration flow to a widget happens in the widget editor. These are two different things. > **📷 Screenshots needed (side by side):** (1) Settings → Configurations page showing key-value pairs. (2) Widget editor → Actions section showing where a Configuration Flow is linked. Label them clearly to show these are two different places. ### MCP (Model Context Protocol) An open protocol that lets AI agents discover and use tools. Fastn's UCL product implements an MCP server that exposes your connectors as tools. AI assistants (Claude, ChatGPT, custom agents) can call these tools to read and write data across your integrations. ### Dashboard Sections When you log into `live.fastn.ai`, the left sidebar shows these sections: | Section | What it does | | ---------------------------- | ------------------------------------------------------------------------------------ | | **Home** | Overview and quick actions | | **Dashboard** | Analytics: integration activity, latency, workflow status | | **Flows** | Build and manage automation workflows | | **Widgets** | Design and manage embedded UI components | | **Triggers** | View and manage webhooks, schedules, and app event triggers | | **Databases** | Database connections for your flows | | **Connectors (Credentials)** | Manage third-party app connections and authentication | | **AI Agent** | Build and test AI agents (Beta) | | **Logs** | Execution history: flow name, request time, duration, HTTP status, tenant ID | | **Trash** | Deleted items | | **Settings** | API Keys, Users, Secrets, Environments, Configurations, Models, Tenants, Preferences | > **Screenshot needed:** Full dashboard left sidebar with all sections visible. Annotate each section label. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.fastn.ai/~/revisions/aj5eaS57qHvafrgYtfbL/fastn-v2/getting-started/key-concepts-and-terminology.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.