Service Connection
A Service Connection is your bridge to any third-party or external application programming interface (API). It enables FlowOn Logic to communicate with external systems—ERPs, payment gateways, shipping providers, marketing platforms, or any service that exposes a REST API.
The Challenge: External System Integration
Modern business processes rarely exist in isolation. They need to interact with external systems:
- Payment processing: Charge credit cards through Stripe or PayPal
- Shipping: Get rates and create shipments via FedEx or UPS
- Communication: Send SMS through Twilio or emails through SendGrid
- Data enrichment: Validate addresses, lookup company information
- Enterprise systems: Sync with SAP, Salesforce, or other platforms
Without a structured approach, integrating with these systems requires custom code, complex authentication handling, and deep technical knowledge. Each API has its own conventions, security requirements, and data formats.
The Solution: Declarative Service Connections
Service Connections provide a no-code approach to external API integration. You configure the connection once—providing the endpoint URL, API specification, and security credentials—and then use it as a simple step in your Logic Flows. FlowOn Logic handles the technical complexity of HTTP requests, authentication, and response parsing.
┌─────────────────────────────────────────────────────────────────────┐
│ SERVICE CONNECTION FLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ DEFINE │ ──► │ CONFIGURE │ ──► │ USE IN │ │
│ │ Connection │ │ Security │ │ FLOWS │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ - Project - API Keys - Call REST API │
│ - Name - OAuth 2.0 Step │
│ - URL - Basic Auth - Select Operation │
│ - OpenAPI Spec - Map Inputs/Outputs │
│ │
└─────────────────────────────────────────────────────────────────────┘
Service Connection Structure
A Service Connection consists of general properties and type-specific configuration:
General Properties
| Property | Required | Description |
|---|---|---|
| Project | Yes | The FlowOn Project this service connection belongs to |
| Name | Yes | Unique identifier for the service connection |
| Description | No | Documentation explaining what this connection is for |
| Type | Yes | The type of service connection (currently supports REST API) |
REST Service Connection Configuration
For REST API connections, you configure:
| Property | Required | Description |
|---|---|---|
| URL | Yes | The base URL of the API (e.g., "https://api.stripe.com/v1") |
| OpenAPI Specification | Yes | The API specification that defines available operations |
| Security Scheme | Yes | How to authenticate requests (API Key, OAuth 2.0, Basic Auth, etc.) |
OpenAPI Specification
The OpenAPI Specification (formerly Swagger) is a standard format for describing REST APIs. It defines:
- Available endpoints (URLs)
- Supported HTTP methods (GET, POST, PUT, DELETE)
- Request parameters and body formats
- Response formats
- Authentication requirements
Most modern APIs provide an OpenAPI specification. You can import this specification into your Service Connection, and FlowOn Logic automatically understands the available operations.
Security Schemes
Service Connections support multiple authentication mechanisms:
API Key
API Key authentication uses a unique key (a long string of characters) to identify and authorize the calling application.
| Property | Required | Description |
|---|---|---|
| Key | Yes | The name of the API key parameter (e.g., "X-API-Key", "api_key") |
| Value | Yes | The actual API key value provided by the service |
| Location | Yes | Where to include the key: Header, Query Parameter, or Body |
When to use: Most third-party APIs use API Key authentication. It's simple to configure and widely supported.
OAuth 2.0
OAuth 2.0 is the industry-standard protocol for authorization. It supports multiple "flows" (grant types) designed for different scenarios:
Client Credentials Flow
Used for server-to-server communication where no user interaction is involved.
| Property | Required | Description |
|---|---|---|
| Access Token URL | Yes | URL where the access token is requested |
| Client ID | Yes | Unique identifier for your application |
| Client Secret | No | Secret known only to your application |
| Scope | No | Permissions being requested |
When to use: Backend integrations, automated processes, service-to-service communication where no user is involved.
Authorization Code Flow
The most secure flow for web applications where a user explicitly grants permission.
| Property | Required | Description |
|---|---|---|
| Access Token URL | Yes | URL where the access token is requested |
| Client ID | Yes | Unique identifier for your application |
| Client Secret | No | Secret known only to your application |
| Auth URL | No | URL where user authorizes the application |
| Callback URL | No | URL where user is redirected after authorization |
| Scope | No | Permissions being requested |
When to use: User-facing integrations where users must explicitly grant permission to access their data.
Using Service Connections in Flows
Once a Service Connection is configured, you use it in Logic Flows through the Call REST API step:
- Select Service Connection: Choose from your configured connections
- Select Operation: Pick from available API operations (parsed from the OpenAPI Specification)
- Map Inputs: Provide values for required parameters (from flow variables, inputs, or expressions)
- Map Outputs: Capture response data into flow variables for further processing
The Call REST API step handles all the technical details—constructing the HTTP request, adding authentication headers, sending the request, and parsing the response.
Example: Payment Processing Service Connection
Service Connection: StripePayments
Project: E-Commerce
Type: REST API
┌─────────────────────────────────────────────────────────────────────┐
│ CONFIGURATION │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ URL: https://api.stripe.com/v1 │
│ │
│ OpenAPI Specification: stripe-api-spec.json │
│ - POST /charges (Create a charge) │
│ - GET /charges/{id} (Retrieve a charge) │
│ - POST /refunds (Create a refund) │
│ - GET /customers/{id} (Retrieve a customer) │
│ - ... (100+ operations) │
│ │
│ Security Scheme: API Key │
│ - Key: Authorization │
│ - Value: Bearer sk_live_xxxxxxxxxxxxx │
│ - Location: Header │
│ │
└─────────────────────────────────────────────────────────────────────┘
Usage in a Flow:
Flow: ProcessOrderPayment
Steps:
1. [Get Entity by ID] - Retrieve Order details
2. [Get Entity by ID] - Retrieve Customer payment info
3. [Call REST API]
- Service Connection: StripePayments
- Operation: POST /charges
- Inputs:
- amount: Order.TotalAmount * 100 (Stripe uses cents)
- currency: "usd"
- customer: Customer.StripeCustomerId
- description: Format("Order {0}", Order.OrderNumber)
- Outputs:
- ChargeId → PaymentChargeId (variable)
- Status → PaymentStatus (variable)
4. [Condition] - If PaymentStatus = "succeeded"
- True: Update Order status to "Paid"
- False: Update Order status to "Payment Failed"
Example: Shipping Integration Service Connection
Service Connection: FedExShipping
Project: Fulfillment
Type: REST API
┌─────────────────────────────────────────────────────────────────────┐
│ CONFIGURATION │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ URL: https://apis.fedex.com │
│ │
│ OpenAPI Specification: fedex-api-spec.json │
│ - POST /rate/v1/rates/quotes (Get shipping rates) │
│ - POST /ship/v1/shipments (Create shipment) │
│ - POST /track/v1/trackingnumbers (Track package) │
│ │
│ Security Scheme: OAuth 2.0 (Client Credentials) │
│ - Access Token URL: https://apis.fedex.com/oauth/token │
│ - Client ID: l7xxxxxxxxxxxxxxxxxxxx │
│ - Client Secret: xxxxxxxxxxxxxxxxxxxxxxxx │
│ - Scope: (empty) │
│ │
└─────────────────────────────────────────────────────────────────────┘
Best Practices
Store Credentials Securely: API keys and secrets are sensitive. FlowOn Logic stores these securely, but ensure you're using production keys only in production environments.
Use Meaningful Names: Name service connections clearly: "StripePayments", "FedExShipping", "TwilioSMS" rather than "Connection1" or "API".
Document the Purpose: Use the description field to explain what the connection is for and any important notes about its configuration.
Handle API Errors: APIs can fail—network issues, rate limits, invalid data. Design your flows to handle error responses gracefully.
Respect Rate Limits: Many APIs limit how many requests you can make per minute/hour. Design flows to stay within these limits, especially in loops or scheduled jobs.
Keep Specifications Updated: If the external API changes, update your OpenAPI Specification to match. Outdated specifications can cause unexpected failures.
Test in Development First: Configure and test service connections in a development environment before using them in production flows.
Use Appropriate Security: Choose the security scheme that matches the API's requirements. When OAuth 2.0 is available, prefer Client Credentials flow for server-to-server integrations.
Monitor Usage: Keep track of API calls, especially for paid services. Unexpected spikes might indicate flow issues or misconfiguration.