Set up Flowcore v2

This guide prepares everything you need before publishing your first Flowcore event. By the end, you will understand which deployment model you are using, have access to a tenant, and have the CLI and TypeScript packages installed.

Before you begin

You need:

• Node.js 18 or newer for the Flowcore CLI
• A Flowcore tenant you are allowed to use
• Permission to create or use a data core, flow types, and event types
• An API key for application access
• A recent npm-compatible package manager

Use a development tenant or environment for the tutorial. Do not experiment with event contracts or replay against production resources.

Choose how the Flowcore platform is operated

Flowcore can be consumed as a managed platform or installed into a dedicated Kubernetes cluster. The event model and application APIs are similar in both cases; the operational responsibility is different.

Managed Flowcore

Choose the managed platform when you want Flowcore to operate the event storage, platform services, control plane, and managed Data Pathway workers.

This is normally the best starting point because your team can focus on event contracts and consumers rather than operating the underlying platform.

Managed Flowcore is a good fit when:

• You want the shortest path to publishing events.
• The managed regions and network model meet your requirements.
• Platform capacity can be handled through plans and quotas.
• You do not need to control the underlying Kubernetes cluster.

Your application still owns its business logic, read models, credentials, and delivery endpoints.

Dedicated Flowcore

Choose a dedicated deployment when data residency, network isolation, infrastructure policy, or self-hosting requirements justify operating Flowcore in your own Kubernetes environment.

A dedicated deployment means your organization owns additional work, including:

• Kubernetes capacity and upgrades
• Flowcore licensing and platform configuration
• Storage, ingress, DNS, and certificates
• Tenant bootstrap and IAM
• Secrets and credentials
• Metrics, logs, alerts, and health monitoring
• Backup, recovery, and maintenance procedures

Do not choose a dedicated deployment simply because your application runs in Kubernetes. Your application can run in your own cluster while using the managed Flowcore platform.

Platform deployment and pathway mode are different decisions

Two choices use similar terminology but solve different problems:

1. Managed or dedicated Flowcore decides who operates the Flowcore platform.
2. Managed or virtual Data Pathway decides where event delivery workers run.

A service using managed Flowcore can still use either managed Data Pathways or a virtual pathway. Keep these decisions separate when discussing architecture.

Confirm your tenant

A tenant is the ownership and security boundary for Flowcore resources. Before writing code, confirm:

• The tenant's exact name or identifier
• Whether it is development, staging, or production
• Who administers access
• Which data core your application should use
• Whether your application may provision resources automatically

Do not guess a tenant name from a company or project name. Resource paths and permissions depend on the exact tenant identifier.

If you need a review of the hierarchy first, read Core concepts and the event data model.

Install the Flowcore CLI

Install the CLI globally:

npm install -g @flowcore/cli

Verify the installation:

flowcore --version
flowcore help

The CLI is useful for interactive login, profiles, manifest validation, resource diffs, applying v2 resources, and inspecting event streams.

Sign in interactively

Run:

flowcore login
flowcore whoami

The login command opens an OAuth flow in your browser. whoami confirms which user and profile the CLI will use.

Interactive login is intended for people. Do not copy a user's stored bearer token into an application or CI environment.

Use profiles for multiple environments

If you work with more than one environment, use named CLI profiles and verify the active identity before applying resources.

The exact endpoint configuration can differ for managed and dedicated installations. Obtain the profile values from your Flowcore administrator rather than copying a production endpoint into local configuration.

A safe workflow is:

1. Create separate development and production profiles.
2. Run flowcore whoami with the intended profile.
3. Run a diff before every apply.
4. Require explicit approval for production changes.

Create application credentials

Applications normally use API keys for supported REST, ingestion, and Pathways operations. User login and API keys serve different purposes:

• A bearer token represents an interactive user and is required by some user-oriented or GraphQL-backed operations.
• An API key represents an application or automation identity and is supported by most current REST commands and event workflows.

Create a separate named key for each application and environment. Grant only the permissions required to publish, query, provision, or operate the relevant resources.

When a key is created:

1. Copy the value immediately.
2. Store it in a secret manager.
3. Do not commit it to source control.
4. Do not include it in logs or error reports.
5. Record the owner and rotation procedure.

Flowcore API keys use a value shaped like fc_<id>_<secret>. Treat the entire value as sensitive.

For local development, expose the key through an ignored environment file or your shell:

FLOWCORE_TENANT=your-development-tenant
FLOWCORE_API_KEY=fc_replace_with_your_key

Never place a real key in example code, frontend bundles, or browser-accessible environment variables.

Install the TypeScript packages

Flowcore provides two complementary application packages.

Pathways

Install @flowcore/pathways when you want typed event contracts, publishing, handlers, provisioning, local or virtual pumping, and managed pathway configuration.

npm install @flowcore/pathways zod

Zod provides runtime validation for event payloads. This matters because TypeScript types alone do not validate data at runtime.

SDK

Install @flowcore/sdk when you need direct typed commands for platform resources, ingestion, queries, IAM, secrets, or Data Pathway operations.

npm install @flowcore/sdk

A client can authenticate with an API key:

import { FlowcoreClient } from "@flowcore/sdk"
 
const client = new FlowcoreClient({
  apiKey: process.env.FLOWCORE_API_KEY!,
})

Some GraphQL-backed and user-oriented command categories require an OAuth bearer token instead. Check the authentication requirement for the command you are using; an API key and bearer token are not interchangeable in every API.

Understand the tools before using them

Use each tool for its intended job:

• CLI: interactive access, profiles, manifests, diffs, applies, and operational inspection
• SDK: direct platform and data commands from TypeScript
• Pathways: event contracts, publishing, handlers, provisioning, and processing runtime

You do not need all three in every service. A small event-producing application may only need Pathways. An administration service may use the SDK. A platform engineer may spend most of their time with the CLI and manifests.

Protect package and platform changes

Before production use:

• Pin dependency versions through your lockfile.
• Review release notes before upgrading Pathways, the SDK, or CLI.
• Test resource provisioning and event delivery in a non-production tenant.
• Treat changes to auto-provisioning behavior as infrastructure changes.
• Keep credentials and environment identifiers outside reusable source code.

Setup checklist

You are ready for the tutorial when all of these are true:

• You know whether the Flowcore platform is managed or dedicated.
• You have the exact development tenant identifier.
• You know which data core the tutorial may create or use.
• flowcore --version succeeds.
• flowcore whoami shows the expected user and profile.
• Your application has a development API key with limited permissions.
• The key is stored outside source control.
• @flowcore/pathways and Zod are installed.

Continue with Build your first event pipeline.