User API Keys for External Services

Beyond LLM providers, many workflows integrate with external services that require API keys. This tutorial explains FlowDot's secure key management system.

The Two Types of Keys

Type	Purpose	Example
LLM API Keys	AI model providers	OpenAI, Anthropic
User API Keys	External services	OpenWeather, Discord

This tutorial focuses on User API Keys.

---

How User API Keys Work

For Workflow Users

When you run a workflow that needs external services:

1. The workflow specifies which keys it needs
2. You see a notification: "This workflow requires: OpenWeather Key"
3. You add your key in Settings > User API Keys
4. The workflow can now use your key securely

For Workflow Designers

When you build workflows:

1. Use the {{key_name}} syntax to reference user keys
2. Add a Key Requirements node to inform users
3. Optionally, share your own keys for public workflows

---

Step 1: Adding User API Keys

1. Click the hamburger menu > API Settings
2. Go to the User API Keys tab
3. Click Create New Key
4. Enter:
   • Key Name: e.g., open_weather_key
   • Key Value: Your actual API key
5. Click Create

Important: Key names are case-sensitive. Use the exact name the workflow expects.

---

Step 2: Using Keys in Workflows

In HTTP Request Nodes

Reference keys with double curly braces:

https://api.openweathermap.org/data/2.5/weather?q=Buffalo&appid={{open_weather_key}}

FlowDot replaces {{open_weather_key}} with your stored value.

In Script Nodes

const apiKey = properties.userApiKey; // Configured to use your key
const response = await fetch(`https://api.example.com?key=${apiKey}`);

In Text Inputs

You can also use keys in any text field:

Bearer {{my_auth_token}}

---

Step 3: The Key Requirements Node

Workflow designers should inform users what keys are needed.

Adding Key Requirements

1. Open Developer Tools category
2. Drag the Key Requirements node onto your canvas
3. Configure:
   • Header Text: "This workflow requires:"
   • Key Name: The exact key name (e.g., open_weather_key)
   • Purpose: "Access to OpenWeather API"
   • Help Link: URL where users can get the key
   • Additional Info: "Sign up free at openweathermap.org"

What Users See

When users open your workflow dashboard:

• A notification shows required keys
• Status indicators show which keys they have/need
• A Configure button opens settings
• A Get Key link goes to your specified URL

---

Step 4: Designer-Provided Keys

Workflow designers can share their own keys for public workflows.

The Shared Keys Node

1. Open Developer Tools category
2. Drag the Shared Keys node onto your canvas
3. Configure with your actual API keys

Important: When someone copies your workflow, shared keys are NOT copied. They remain yours alone.

Use Cases for Shared Keys

• Demo workflows that "just work"
• Public utilities for the community
• Workflows where you want to control API usage

When NOT to Share Keys

• Keys with usage limits you can't afford to share
• Keys tied to personal accounts
• Keys for paid services

---

Security Model

Your Keys Are Protected

• Keys are encrypted in the database
• Other users cannot see your key values
• Keys are only used when you run workflows
• Workflow designers cannot extract your keys

Key Scope

Scenario	Key Used
You run your own workflow	Your keys
You run a public workflow	Your keys
Someone copies your workflow	Their keys (yours not copied)
Designer shares keys	Designer's keys (for that workflow only)

---

Example: Weather Workflow

Designer Setup

1. Create workflow with HTTP Request node
2. Set URL: https://api.openweathermap.org/data/2.5/weather?q={{city}}&appid={{open_weather_key}}
3. Add Key Requirements node:
   • Key: open_weather_key
   • Link: https://openweathermap.org/api

User Experience

1. User opens workflow dashboard
2. Sees: "This workflow requires: open_weather_key"
3. Clicks Configure > adds their free OpenWeather key
4. Refreshes - status shows green checkmark
5. Runs workflow successfully

---

Common External Service Keys

Service	Key Name Convention	Free Tier?
OpenWeather	open_weather_key	Yes
Discord	discord_bot_token	Yes
Slack	slack_webhook_url	Yes
GitHub	github_token	Yes
Notion	notion_api_key	Yes
Airtable	airtable_api_key	Yes
Stripe	stripe_secret_key	Test mode free

---

Troubleshooting

"Key Not Found"

• Check the exact key name (case-sensitive)
• Ensure no extra spaces
• Verify the key is saved in User API Keys

"Unauthorized" from External Service

• Verify your key is valid
• Check if the service requires additional setup
• Some APIs need you to enable specific permissions

Key Works Locally But Not in Workflow

• Ensure you're using {{key_name}} syntax
• Check if the workflow expects a different key name
• Review the Key Requirements node for the expected name

---

Summary

User API Keys let you:

• Securely store credentials for external services
• Use keys in workflows without exposing them
• Share workflows that require keys (users provide their own)
• Optionally share your keys for public workflows

Next, learn about copying and customizing public workflows!