> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects and API keys

> What a Flowra project is, project settings tabs, API keys, and AI Key (OpenRouter).

A **project** is your main **workspace** in Flowra: the boundary for API keys, shared tool setup, MCP, and the container for all end users and their automations.

It is **not** your dashboard login, and it is **not** an [external user](/product/external-users). Your login can access several projects; each project has its own switcher entry, settings, and keys.

## What you can do inside a project

Almost the whole product runs inside the active project:

| Area | What you do |
| - | - |
| **Agents & workflows** | Build in chat or the editor; static graphs or conversational agents |
| **Tools** | Use 20,000+ toolkit tools; create custom JS/Python tools; browse Toolkits & Tools |
| **Connections** | OAuth-link Slack, Gmail, Telegram, and other apps (per end user) |
| **Entry points** | Dashboard chat, MCP, messaging channels, schedules, events, site [widgets](/product/widgets-and-embeds) |
| **Data** | Knowledge (RAG), tables/database, files |
| **Skills** | Attach reusable playbooks to agents |
| **MCP** | Register servers; expose tools to Cursor / Claude |
| **Runtime** | Sandbox code runs, live browser sessions |
| **Templates** | Clone workflow templates into this project |
| **Multi-tenant** | Many [external users](/product/external-users) under one project |
| **API** | Call the same capabilities with a project API key |

Credits and plan limits apply at account level; optional **own OpenRouter key** can be set per project on paid plans — see [Account and pricing](/product/account-and-pricing).

## Nested map: project vs external user

Everything sits under your **account**, then a **project**, then optionally many **external users**:

```text theme={null}
Your Flowra account (dashboard login)
└── Project  ← sidebar project switcher · one API key binds here
    │
    ├── Shared across the project (not “owned” by one end user)
    │   ├── Project settings (General, API Keys, AI Key, Webhook, Application, End users)
    │   ├── Flowra API keys
    │   ├── Optional OpenRouter (BYOK) AI key
    │   ├── App credentials (auth configs)
    │   ├── Toolkits & custom tools (project LOCAL tools + catalog access)
    │   ├── MCP servers
    │   ├── Templates (browse; clone lands in this project)
    │   ├── External users directory (list / create usernames)
    │   ├── Trigger instances (schedule / event subscriptions)
    │   └── Files (project file library)
    │
    └── External user (eUID)  ← sidebar End user switcher · x-username on API
        ├── Connected accounts (that person’s Slack, Gmail, …)
        ├── Workflows & agents (ownerEUID) + executions
        ├── Skills
        ├── Knowledge collections (RAG)
        ├── Tables / database collections
        ├── Chat threads
        └── Tool runs that use this user’s connections
```

| Layer | Pick with | Typical use |
| - | - | - |
| **Account** | Sign-in | Billing, pricing, support |
| **Project** | Project switcher | Separate apps, environments (dev/prod), or departments |
| **External user** | End user switcher / `x-username` | Each customer or person inside one product |

**Rule of thumb:** Use **another project** when you want a hard split (different API keys, tool setups, MCP). Use **another external user** when the same product should keep each person’s OAuth tokens and data apart.

Deep API matrix: [Multi-tenancy](/guides/multi-tenancy).

## Create and switch projects

<Steps>
  <Step title="Open projects">
    Use **Add project** on the switcher, or go to [Projects](https://flowra.dev/dashboard/projects).
  </Step>

  <Step title="Create">
    Open [Create project](https://flowra.dev/dashboard/projects/create). Enter at least a **Project Name** (description optional) and submit. Other settings tabs unlock after create.
  </Step>

  <Step title="Open Project settings">
    From the switcher gear or the projects list, open **Project Settings**. The header shows the project name, id, and **Active** / **Inactive** badge.
  </Step>
</Steps>

After you select a project, pick the right **End user** before connecting accounts or testing chat — see [External users switcher](/product/external-users).

## Project settings

Settings use these tabs (other tabs stay locked until the project exists):

### General

| Field | Meaning |
| - | - |
| **Project Name** | Required display name |
| **Description** | Optional notes |
| **Region** | Country filter for templates. Toolkits still include **Global** plus this country. Leave **Global** for worldwide-only catalogs |
| **Active** | When off, the project stays in your list but is paused for new work |

### API Keys

Create and revoke Flowra API keys for this project. See [Flowra API keys](#flowra-api-keys) below.

### AI Key

Section title: **AI Key (OpenRouter)**. Paste an **OpenRouter API key** so model usage for this project bills through your OpenRouter account instead of platform credit.

* Leave blank to keep the current key.
* Not available on the free plan — upgrade to Starter or Pro. Create a key at [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys).

### Webhook

Section: **Webhook Settings**.

| Field | Meaning |
| - | - |
| **Webhook URL** | HTTPS endpoint that receives HTTP callbacks when events occur (for example workflow runs) |
| **Webhook Secret** | Shared secret for verifying requests on your server |

Use **Generate** to create a random secret. Your server should validate the signature sent in the request headers with this secret.

### Application

Section: **Application Settings** — how your app appears on the OAuth **consent page**.

| Field | Meaning |
| - | - |
| **App Title** | Name shown on consent |
| **Upload app logo** | Logo shown on consent |

A live **Consent page preview** sits beside the form.

### End users

This tab has two sections.

#### End-user capabilities

Controls what **secondary** end users (not the project default) can create for themselves. The project default user can always create these.

| Toggle | When On |
| - | - |
| **Allow end-user agents & workflows** | Secondary users may create and edit their own agents and workflows |
| **Allow end-user database collections** | Secondary users may create, rename, or delete database collections |
| **Allow end-user knowledge collections** | Secondary users may create, rename, or delete knowledge collections |

When a toggle is Off, related dashboard surfaces show a capability gate pointing back to these settings. Connections and chat stay per user either way.

#### End-user identity verification

**HMAC** and **JWT** secrets so the website widget and SDK can prove who the visitor is (separate from toolkit OAuth).

| Setting | Use |
| - | - |
| **HMAC secret** | Widget: your server sends `data-user-id` + `data-user-hash` (HMAC-SHA256 of the user id). Rotate to reveal a new secret once. |
| **JWT** | Widget (`data-user-token`) or SDK (`X-End-User-Token`). Configure algorithm, secret or JWKS URL, issuer, and audience as the form asks. |

Create and save the project first, then generate secrets here. On each agent, turn on visitor identity under **Identity** → **End-user identity** (and methods such as Host HMAC / Host JWT). See [Widgets and embeds](/product/widgets-and-embeds) and [Workflows in the dashboard](/product/workflows-in-dashboard).

## Flowra API keys

API keys authenticate calls to the Flowra API for **one project**. One key cannot reach another project.

<Steps>
  <Step title="Open API Keys">
    In **Project Settings**, open the **API Keys** tab (or **Project → API Keys**).
  </Step>

  <Step title="Create a key">
    Create a key, give it a clear name (for example `Backend prod`), and copy it once. You will not see the full value again.
  </Step>

  <Step title="Store it securely">
    Keep the key in a secrets manager or environment variable. Do not commit it or expose it in client-side apps. For multi-tenant apps, your backend holds the key and sends `x-username` per end user.
  </Step>
</Steps>

How to send the key: [Authentication](/authentication). First request: [Quickstart](/quickstart).

## Related

* [App credentials](/product/app-credentials) — Project OAuth / API-key configs for toolkits
* [Account and pricing](/product/account-and-pricing)
* [How Flowra works](/product/how-flowra-works)
* [External users switcher](/product/external-users)
* [Templates](/product/marketplace)
* [Multi-tenancy](/guides/multi-tenancy)
* [Authentication](/authentication)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.