Platform Overview

Supaship organizes your feature flags into a simple hierarchy: Organizations → Projects → Environments → Feature Flags. Understanding this structure helps you organize your teams and releases effectively.

Organizations

Organizations are the top-level containers in Supaship. It typically represents your company, department, or team.

• An organization can have multiple projects.
• You can invite members (teammates) to collaborate.
• Access to projects and resources is controlled by roles.

Members & Roles

Members are users within an organization. They have access to projects, environments, and feature flags depending on their role:

• OWNER – Full administrative rights, including managing members, projects, and billing.
• MEMBER – Can work within projects but with limited administrative privileges.

Project

A Project represents a software application or service. Projects are where your environments, flags, and configurations live.

• Each project contains one or more environments (like dev, staging, prod).
• Projects also hold context properties and API keys used for flag evaluation.

Environment

Environments represent different stages of your development lifecycle (e.g., development, staging, production).

• By default, Supaship creates two environments: development and production.
• You can add more environments as needed.
• Feature flag targeting rules are environment-specific, so you can safely test changes before pushing them live.

Feature Flags

Feature flags are switches that control features in your application. They live inside environments and can be targeted to specific users or groups.

• Boolean Flags – Simple on/off switches (true/false)
• JSON Flags – Return structured data for complex configurations

When you evaluate a flag, Supaship returns a variation (the value) based on your targeting rules. For boolean flags, this is true or false. For JSON flags, it’s a structured object.

Context Properties

Context properties are user attributes you send with each flag evaluation (like userID, email, country). Supaship uses these to evaluate targeting rules and decide which variation to return.

Example:

const result = await client.getFeature('new-checkout', {
  context: {
    userID: '123',
    plan: 'premium',
    country: 'US',
  },
})
// Supaship checks these properties against your targeting rules

Targeting & Segments

Targeting lets you control who sees which variation of a feature flag. You create rules based on user context properties (like country = 'US' or plan = 'premium').

Segments are reusable user groups you can reference in targeting rules:

• Conditional Segments – Dynamic groups based on conditions (e.g., “all premium users”)
• List Segments – Static lists of specific users (e.g., beta testers)

How it works together:

1. Create a segment (e.g., “Premium Users”)
2. Reference it in feature flag targeting rules
3. Update the segment once, all flags using it update automatically

You can also combine targeting with percentage rollouts (e.g., “show to 50% of premium users”) for gradual rollouts.

API Keys

API Keys authenticate requests to Supaship when evaluating flags.

• Client Keys – Used in frontend or client-side apps. These are limited in scope and safe to expose publicly.
• Server Keys – Used in backend services. These provide more control and access, and should be kept secret.

Both types of keys are tied to a project, and can be used in multiple environments.

Analytics

Track feature usage, performance, and user behavior to make data-driven decisions.