Platform Overview

Supaship is built on a few core building blocks that give you fine-grained control over how features are shipped, tested, and rolled back. Understanding these concepts will help you model your teams, projects, 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/Configurations

Feature flags are the heart of Supaship. They let you toggle functionality without redeploys.

• Boolean Flags – Simple on/off flags for enabling or disabling a feature.
• JSON Configurations – Flexible configurations for advanced scenarios (e.g., configuring values, variations, or experiments).

Flags live inside environments and can be targeted to specific users or groups.

Variations

A variation is the outcome (value) that Supaship returns when a feature flag is evaluated. Think of it as the “answer” to the question: what should this user see?

Each flag can have one or more variations, depending on the flag type:

• Boolean flags → Two variations: true (on) or false (off).

• Example:

  • Flag: new-checkout-flow
  • Variations:
    true = show new checkout page,
    false = show old checkout page.

• JSON flags → Multiple variations with structured values.

• Example:

  • Flag: api-config
  • Variations:
    • Variation 1: { timeout: 5000, endpoint: ‘/api/v1’ }
    • Variation 2: { timeout: 3000, endpoint: ‘/api/v2’ }

This lets you serve different configurations to different audiences without changing your code.

Context Properties

Context properties are the attributes you send along with a flag evaluation request. These properties power user targeting rules.

Examples:

• userId
• email
• country
• appVersion

When your app calls the evaluation API (directly or via SDK), Supaship checks the context properties against targeting rules to decide what variation to return.

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.

User Targeting

Targeting allows you to decide who sees what for a given flag.

• Targeting is configured per environment.
• Rules consist of conditions (e.g., “country = IN” or “appVersion > 5.0”).
• Each rule can be assigned a percentage rollout (e.g., 50% of users).
• If no rule matches, the default variation is served.

This makes it possible to:

• Roll out gradually (start at 1%, then ramp up).
• Target by user attributes (region, app version, cohort).
• Safely roll back if issues occur.

Analytics

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