Local Developer Setup

How to configure personal API tokens for local development environments.

Overview

Each developer on your team should use their own personal API token for local development. This provides several benefits:

• Track which developer is making API requests
• Revoke access for individual developers without affecting the team
• Avoid sharing credentials across machines
• Enable per-developer feature flag overrides

Step 1: Create a Personal Environment

Each developer should create their own personal environment. This gives you an isolated sandbox to test feature flags without affecting other developers.

1. Navigate to your organization's Environments page
2. Click New Environment
3. Enter a name using your identifier (e.g., "john-dev" or "maria-local")
4. Select Development as the parent environment to inherit its flag states
5. Click Create Environment

Step 2: Create a Personal Token

Create an API token scoped to your personal environment:

1. Navigate to your organization's Settings → API Tokens
2. Click New Token
3. Enter a descriptive name (e.g., "John's MacBook" or "Local Dev")
4. Select your personal environment (e.g., "john-dev")
5. Choose Read & Write permission to enable local flag management
6. Click Create Token

Personal tokens are prefixed with fs_personal_ to distinguish them from shared organization tokens.

Step 3: Configure Your Environment

Add your personal token to your local environment. Choose the method that best fits your project's setup. Never commit tokens to version control.

Option A: Using direnv

direnv automatically loads environment variables when you enter a directory. Create an .envrc file in your project root:

export FLAGSTACK_TOKEN="fs_personal_your_token_here"

Then allow the file:

direnv allow

Option B: Using a .env file

If your project uses dotenv, create or update your local .env file:

# Flagstack personal token for local development
FLAGSTACK_TOKEN=fs_personal_your_token_here

Option C: Using your shell profile

Export the token globally in your shell configuration:

export FLAGSTACK_TOKEN="fs_personal_your_token_here"

Reload your shell or run source ~/.zshrc to apply.

Step 4: Verify Configuration

Start your Rails application and verify Flagstack is configured correctly:

# Check if Flagstack is configured
Flagstack.configured?
# => true

# Test a feature flag
Flipper.enabled?(:my_feature)
# => true/false

Team Setup Recommendations

For teams adopting Flagstack, we recommend the following setup:

1. Document the setup process

Add instructions to your project's README or onboarding documentation:

## Feature Flags Setup

1. Create a personal environment at https://flagstack.io/<org>/environments
   - Name it with your identifier (e.g., yourname-dev)
   - Set Development as the parent environment
2. Create a personal API token at https://flagstack.io/<org>/settings/api_tokens
   - Scope it to your personal environment
   - Use Read & Write permission
3. Set the FLAGSTACK_TOKEN environment variable (see .envrc.example)

2. Provide an example environment file

Include an example file in your repository to show developers which variables are needed:

# Flagstack - Get your personal token from Settings → API Tokens
export FLAGSTACK_TOKEN=# your personal token here

3. Configure environment-specific tokens

Use different tokens for different environments in your application:

Flagstack.configure do |config|
  config.token = if Rails.env.production?
                   ENV["FLAGSTACK_PRODUCTION_TOKEN"]
                 elsif Rails.env.staging?
                   ENV["FLAGSTACK_STAGING_TOKEN"]
                 else
                   # Local development uses personal tokens
                   ENV["FLAGSTACK_TOKEN"]
                 end
end

Security Best Practices

• Never commit tokens to version control
• Use personal environments so write access only affects your own sandbox
• Rotate tokens periodically or when a developer leaves the team
• Use environment-scoped tokens to limit access to production data
• Delete unused tokens promptly from the API Tokens settings

Troubleshooting

Token not being recognized

Verify your token is set correctly:

echo $FLAGSTACK_TOKEN
# Should output: fs_personal_...

Feature flags not syncing

Check that your token has access to the correct environment and that your application can reach the Flagstack API:

# Force a sync
Flagstack.sync!

# Check last sync status
Flagstack.last_sync_at