Quickstart

Step 1: Create an IAM Role

In your AWS account, create a new IAM role with a trust relationship that allows FlagDrop to assume it.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::FLAGDROP_ACCOUNT_ID::root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_ORG_EXTERNAL_ID"
        }
      }
    }
  ]
}

Replace FLAGDROP_ACCOUNT_ID and YOUR_ORG_EXTERNAL_ID with the values shown in your FlagDrop dashboard under Environment settings.

Step 2: Attach S3 Permissions

Attach the following inline policy to the role. This grants FlagDrop the minimum permissions needed to write configuration files.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

Step 3: Enter the Role ARN

Copy the Role ARN from the AWS console and paste it into the FlagDrop dashboard under your environment's cloud connection settings.

Step 4: Test the Connection

Click Test Connection in the dashboard. FlagDrop will attempt to assume the role and write a test object to your bucket. A green checkmark confirms everything is configured correctly.

Step 1: Create a Service Account

In the Google Cloud Console, navigate to IAM & Admin > Service Accounts and create a new service account. Grant it the Storage Object Admin role on your target bucket.

$ gcloud iam service-accounts create flagdrop-writer \
    --display-name="FlagDrop Config Writer"

$ gcloud storage buckets add-iam-policy-binding \
    gs://YOUR_BUCKET_NAME \
    --member="serviceAccount:flagdrop-writer@YOUR_PROJECT.iam.gserviceaccount.com" \
    --role="roles/storage.objectAdmin"

Step 2: Generate a JSON Key

Go to IAM & Admin > Service Accounts, click the service account, then Keys > Add Key > Create new key > JSON.

Step 3: Download the Key File

The JSON key file will download automatically. Keep it secure — this grants write access to your bucket.

Step 4: Paste into FlagDrop

In your environment's cloud connection settings, select GCP (Service Account Key) as the auth method. Paste the full JSON contents of the key file into the auth config field.

Step 5: Save and Test

Click Test Connection to verify FlagDrop can write to your bucket. Once confirmed, save the configuration.

Step 1: Create a Workload Identity Pool

$ gcloud iam workload-identity-pools create flagdrop-pool \
    --location="global" \
    --display-name="FlagDrop Pool"

Step 2: Add an AWS Provider

$ gcloud iam workload-identity-pools providers create-aws flagdrop-aws \
    --location="global" \
    --workload-identity-pool="flagdrop-pool" \
    --account-id="FLAGDROP_AWS_ACCOUNT_ID"

Step 3: Create and Bind a Service Account

$ gcloud iam service-accounts create flagdrop-sa \
    --display-name="FlagDrop Service Account"

$ gcloud iam service-accounts add-iam-policy-binding \
    flagdrop-sa@YOUR_PROJECT.iam.gserviceaccount.com \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/flagdrop-pool/attribute.aws_role/arn:aws:sts::FLAGDROP_ACCOUNT_ID:assumed-role/flagdrop-role"

$ gcloud storage buckets add-iam-policy-binding \
    gs://YOUR_BUCKET_NAME \
    --member="serviceAccount:flagdrop-sa@YOUR_PROJECT.iam.gserviceaccount.com" \
    --role="roles/storage.objectAdmin"

Step 4: Enter in FlagDrop

Select GCP (Workload Identity) as the auth method. Enter the Workload Identity Provider resource name and the service account email. FlagDrop will exchange its AWS credentials for short-lived GCP tokens automatically.

Step 1: Generate a SAS Token

In the Azure Portal, navigate to your Storage Account > Shared access signature. Configure the following permissions:

Step 2: Enter in FlagDrop

Select Azure (SAS Token) as the auth method. Enter your Storage Account name, container name, and the SAS token. Click Test Connection to verify.

Step 1: Register an Azure AD Application

In Azure Portal, go to Azure Active Directory > App registrations > New registration. Name it something like flagdrop-federation.

Step 2: Add a Federated Credential

Under Certificates & secrets > Federated credentials, add a new credential:

Step 3: Grant Storage Blob Data Contributor

$ az role assignment create \
    --assignee "APP_CLIENT_ID" \
    --role "Storage Blob Data Contributor" \
    --scope "/subscriptions/SUB_ID/resourceGroups/RG/providers/Microsoft.Storage/storageAccounts/ACCOUNT"

Enter the Application (client) ID and Tenant ID in FlagDrop. Select Azure (Workload Identity) as the auth method.

Adding Region Destinations

In your environment's settings, click Add Region to configure additional destinations. Each region gets its own cloud connection (bucket, credentials, and region). When you push config, FlagDrop writes to all destinations in parallel.

Use Cases

List all flags in a project:

$ curl -s https://api.flagdrop.io/api/v1/projects/web-app/flags \
    -H "Authorization: Bearer YOUR_TOKEN"

Create a new boolean flag:

$ curl -s -X POST https://api.flagdrop.io/api/v1/projects/web-app/flags \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "key": "new_checkout_flow",
  "type": "boolean",
  "description": "Enable the redesigned checkout",
  "defaultValue": false
}'

Toggle a flag on or off:

$ curl -s -X POST https://api.flagdrop.io/api/v1/projects/web-app/flags/new_checkout_flow/toggle \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "environment": "staging", "enabled": true }'

Push config to an environment:

$ curl -s -X POST https://api.flagdrop.io/api/v1/projects/web-app/push/production \
    -H "Authorization: Bearer YOUR_TOKEN"

Set a percentage rollout:

$ curl -s -X POST https://api.flagdrop.io/api/v1/projects/web-app/flags/new_checkout_flow/rollout \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "environment": "production", "percentage": 25 }'

Flag Naming Conventions

Use snake_case for all flag keys. Keep them descriptive and scoped to the feature they control.

Flag Lifecycle Management

Every flag should progress through a defined lifecycle. Stale flags add complexity and technical debt.

Once a flag reaches full rollout and the feature is stable, remove the flag from your code and delete it from FlagDrop. FlagDrop marks flags as stale if they haven't been modified in 30 days while still enabled.

Rollout Strategies

Testing Flags in Staging vs Production

FlagDrop environments are independent. Each environment has its own flag states, rollout percentages, and cloud connections.

Frontend Relay Pattern

For client-side feature flags, use the relay pattern: FlagDrop pushes a JSON configuration file to your cloud storage. Serve it through a CDN and evaluate flags client-side for zero-latency decisions.

// Fetch the flag config from your CDN-backed bucket
const res = await fetch('https://cdn.example.com/flags/production.json')
const config = await res.json()

// Evaluate locally — no network call per flag
const showBanner = config.flags['promo_banner']?.enabled ?? false
const rollout = config.flags['new_checkout_flow']?.rolloutPercentage ?? 0

// Hash the user ID for deterministic percentage rollout
const userBucket = hashUserId(userId) % 100
const inRollout = userBucket < rollout

This pattern keeps flag evaluation under 1ms. The JSON file is typically under 10KB and caches well at the CDN edge. Set a short TTL (30-60s) to balance freshness with performance.