Authentication

FreeState uses API keys for authentication. This guide covers how to generate, manage, and use API keys securely with your Terraform configurations.

API Key Overview

FreeState authentication is based on API keys that provide secure access to your workspaces. Each API key has specific permissions and can be scoped to individual workspaces or your entire organization.

Generating API Keys

Via Dashboard

1. Log in to your FreeState dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Provide a descriptive name (e.g., "Production Terraform", "CI/CD Pipeline")
5. Select the appropriate permissions
6. Click Create Key

Via CLI (Coming Soon)

# Generate a new API key
freestate auth generate-key --name "terraform-prod" --scope workspace:prod

API Key Permissions

Permission Levels

Scope Options

• Organization: Access to all workspaces in your organization
• Workspace: Access limited to specific workspaces
• Environment: Access limited to specific environments (dev, staging, prod)

Using API Keys with Terraform

Basic Configuration

terraform {
  backend "http" {
    address        = "https://api.freestate.cloud/terraform/state"
    username       = "your-workspace-id"
    password       = "your-api-key"
    lock_address   = "https://api.freestate.cloud/terraform/state/lock"
    lock_method    = "POST"
    unlock_address = "https://api.freestate.cloud/terraform/state/lock"
    unlock_method  = "DELETE"
  }
}

Using Environment Variables

For better security, use environment variables instead of hardcoded values:

# Set environment variables
export TF_HTTP_USERNAME="your-workspace-id"
export TF_HTTP_PASSWORD="your-api-key"

# Terraform configuration
terraform {
  backend "http" {
    address        = "https://api.freestate.cloud/terraform/state"
    lock_address   = "https://api.freestate.cloud/terraform/state/lock"
    lock_method    = "POST"
    unlock_address = "https://api.freestate.cloud/terraform/state/lock"
    unlock_method  = "DELETE"
  }
}

CI/CD Integration

GitHub Actions

name: Terraform
on: [push]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        
      - name: Terraform Init
        env:
          TF_HTTP_USERNAME: ${{ secrets.FREESTATE_WORKSPACE_ID}}
          TF_HTTP_PASSWORD: ${{ secrets.FREESTATE_API_KEY}}
        run: terraform init
        
      - name: Terraform Plan
        env:
          TF_HTTP_USERNAME: ${{ secrets.FREESTATE_WORKSPACE_ID}}
          TF_HTTP_PASSWORD: ${{ secrets.FREESTATE_API_KEY}}
        run: terraform plan

GitLab CI

terraform:
  image: hashicorp/terraform:latest
  variables:
    TF_HTTP_USERNAME: $FREESTATE_WORKSPACE_ID
    TF_HTTP_PASSWORD: $FREESTATE_API_KEY
  script:
    - terraform init
    - terraform plan
    - terraform apply -auto-approve

Jenkins

pipeline {
  agent any
  environment {
    TF_HTTP_USERNAME = credentials('freestate-workspace-id')
    TF_HTTP_PASSWORD = credentials('freestate-api-key')
  }
  stages {
    stage('Terraform') {
      steps {
        sh 'terraform init'
        sh 'terraform plan'
        sh 'terraform apply -auto-approve'
      }
    }
  }
}

API Key Management

Key Rotation

Regularly rotate your API keys for security:

1. Generate a new API key with the same permissions
2. Update your Terraform configurations and CI/CD systems
3. Test the new key works correctly
4. Revoke the old API key

Monitoring Usage

Monitor API key usage in your dashboard:

• Last used timestamp
• Number of requests
• Failed authentication attempts
• IP addresses and user agents

Revoking Keys

Immediately revoke compromised or unused keys:

1. Go to Settings → API Keys
2. Find the key to revoke
3. Click Revoke
4. Confirm the action

Security Best Practices

Storage

• Store API keys in secure credential management systems
• Never commit API keys to version control
• Use environment variables or secret management tools
• Limit key access to necessary team members

Network Security

• Use HTTPS for all API communications (enforced by FreeState)
• Consider IP whitelisting for production workspaces
• Monitor for unusual access patterns

Principle of Least Privilege

• Grant minimum permissions necessary
• Use workspace-scoped keys when possible
• Separate keys for different environments
• Regular audit of key permissions

Troubleshooting Authentication

Common Issues

401 Unauthorized

• Check API key is correct and not revoked
• Verify workspace ID is correct
• Ensure key has necessary permissions

403 Forbidden

• API key lacks required permissions
• Workspace access restrictions
• IP whitelist restrictions

Connection Issues

# Test API connectivity
curl -H "Authorization: Bearer your-api-key"      https://api.freestate.cloud/v1/workspaces

Multi-Factor Authentication

For enhanced security, enable MFA on your FreeState account. While API keys don't require MFA for Terraform operations, MFA protects your dashboard access and key management operations.

Enabling MFA

1. Go to Settings → Security
2. Click Enable Two-Factor Authentication
3. Scan the QR code with your authenticator app
4. Enter the verification code
5. Save your backup codes securely

API Usage Reference

For comprehensive API usage documentation including authentication patterns, endpoint specifications, and advanced configuration options, refer to the canonical API documentation in the backend repository:

• Backend API Documentation: FreeState- API_USAGE.md
• OpenAPI Specification: Available at https://api.freestate.cloud/v1/openapi.json

Quick Health Check

To verify API connectivity and service health, use the /version endpoint. This endpoint requires no authentication and is useful for monitoring, CI/CD health checks, and troubleshooting.

# Check API version and health status
curl https://api.freestate.cloud/v1/version

# Example response:
{
  "version": "1.2.3",
  "api_version": "v1",
  "status": "healthy",
  "uptime": "72h15m"
}

Use this endpoint in your deployment pipelines to verify the FreeState API is reachable before running Terraform operations.

Cross-Repository Access

Related Repositories

The following FreeState repositories are available for documentation context and reference. Access to these repositories is managed through standard GitHub permissions and is used by development tools (like Copilot) for context during authoring—not by CI/CD pipelines.

• rockminster/FreeState-: Core platform repository
• rockminster/FreeState-Internal: Internal configuration and documentation
• rockminster/FreeState-portal: User portal application
• rockminster/FreeState-site: Marketing website (this repository)