Secrets Reference

This document lists all secrets required for FlowState production deployment, including token scopes and permissions.

API Tokens & Keys

GITHUB_TOKEN

Purpose: Clone private repositories during Docker image builds

Token Type: Fine-grained Personal Access Token (recommended) or Classic PAT

Fine-grained PAT (Recommended)

Classic PAT (Alternative)

How to Create:

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Choose "Fine-grained tokens" (recommended)
3. Set expiration (recommend 1 year for production)
4. Select repository: epic-digital-im/epic-flow-workspace
5. Set permissions: Contents (Read-only)
6. Generate token

RXDB_PREMIUM

Purpose: Access RxDB Premium npm packages during builds

Token Type: npm Access Token from RxDB

Required Scope: Read-only access to rxdb-premium packages

How to Obtain:

1. Purchase RxDB Premium license at https://rxdb.info/premium
2. Receive npm access token via email
3. Token format: npm_xxxxxxxxxxxx

ANTHROPIC_API_KEY

Purpose: Claude AI API access for orchestrator and RAG services

Token Type: Anthropic API Key

Required Permissions:

How to Create:

1. Go to https://console.anthropic.com/
2. Navigate to API Keys
3. Create new key with descriptive name (e.g., "flowstate-prod")
4. Copy key (starts with sk-ant-)

Rate Limits: Ensure your plan supports production workloads

OPENAI_API_KEY

Purpose: OpenAI API access for Agent Memory Server (AMS) embeddings

Token Type: OpenAI API Key

Required Permissions:

How to Create:

1. Go to https://platform.openai.com/api-keys
2. Create new secret key
3. Copy key (starts with sk-)

Note: AMS can also use Ollama for embeddings (configured via OLLAMA_EMBEDDING_MODEL)

SENDGRID_API_KEY

Purpose: Email delivery for authentication codes

Token Type: SendGrid API Key

Required Permissions:

How to Create:

1. Go to https://app.sendgrid.com/settings/api_keys
2. Create API Key
3. Select "Restricted Access"
4. Enable only: Mail Send → Full Access
5. Create & copy key (starts with SG.)

Additional Setup Required:

• Verify sender identity for MAIL_FROM email address
• Go to Settings → Sender Authentication
• Complete domain authentication (recommended) or single sender verification

Encryption Keys

LUKS_KEYFILE

Purpose: Unlock encrypted production volume at boot

Type: Binary key file (4096 bytes random data)

Storage: Base64-encoded in 1Password

Generation:

dd if=/dev/urandom of=/root/.luks-keyfile bs=4096 count=1
chmod 600 /root/.luks-keyfile

Recovery: Required to access data if server is destroyed but volume survives

RXDB_ENCRYPTION_KEY

Purpose: Application-level encryption for RxDB documents (future use)

Type: 256-bit key, base64-encoded

Generation:

openssl rand -base64 32

Current Status: Available but not yet implemented

REDIS_ENCRYPTION_KEY

Purpose: Application-level encryption for Redis values (future use)

Type: 256-bit key, base64-encoded

Generation:

openssl rand -base64 32

Current Status: Available but not yet implemented

JWT Keys

JWT_PRIVATE_KEY

Purpose: Sign JWT tokens for authentication

Type: RSA 2048-bit private key (PEM format)

Used By: Auth Server

Generation:

openssl genrsa -out private.pem 2048

Security: Never expose. Store only in 1Password and on server.

JWT_PUBLIC_KEY

Purpose: Verify JWT token signatures

Type: RSA public key (PEM format)

Used By: Auth Server, RxDB Server, Kong Gateway

Generation:

openssl rsa -in private.pem -pubout -out public.pem

Note: This key is embedded in Kong configuration for JWT validation

Configuration Values

MAIL_FROM

Purpose: Sender email address for authentication emails

Type: Email address string

Requirements:

• Must be verified in SendGrid as a Sender Identity
• Domain authentication recommended for deliverability

Example: noreply@epicflowstate.ai or auth@epicflowstate.ai

RXDB_AUTH_TOKEN

Purpose: Service-to-service authentication for internal API calls

Type: JWT token (long-lived)

Used By: Orchestrator → RxDB Server

Generation: See PRODUCTION.md "Generating Service JWT" section

Claims Required:

{
  "iss": "https://api.epicflowstate.ai",
  "sub": "orchestrator-service",
  "domainId": "flowstate-prod",
  "orgId": "org_xxxxxxxxxx",
  "role": "service",
  "exp": <10 years from now>
}

1Password Vault Structure

Recommended Structure for flowstate-prod Vault

flowstate-prod/
├── GitHub/
│   └── GITHUB_TOKEN              [Password]
├── npm/
│   └── RXDB_PREMIUM              [Password]
├── AI-Services/
│   ├── ANTHROPIC_API_KEY         [Password]
│   └── OPENAI_API_KEY            [Password]
├── Email/
│   ├── SENDGRID_API_KEY          [Password]
│   └── MAIL_FROM                 [Password]
├── Encryption/
│   ├── LUKS_KEYFILE              [Secure Note - base64]
│   ├── RXDB_ENCRYPTION_KEY       [Password]
│   └── REDIS_ENCRYPTION_KEY      [Password]
├── JWT/
│   ├── JWT_PRIVATE_KEY           [Secure Note - PEM]
│   └── JWT_PUBLIC_KEY            [Secure Note - PEM]
└── Service-Tokens/
    └── RXDB_AUTH_TOKEN           [Password]

Service Account Token

OP_SERVICE_ACCOUNT_TOKEN

Purpose: Allow production server to fetch secrets from 1Password

Type: 1Password Service Account Token

Required Vault Access: flowstate-prod (Read)

How to Create:

1. Go to 1Password → Developer → Service Accounts
2. Create new service account
3. Name: flowstate-prod-server
4. Grant access to flowstate-prod vault (Read Items)
5. Copy token (starts with ops_)

Server Setup:

export OP_SERVICE_ACCOUNT_TOKEN="ops_xxxxxxxx"

Security Best Practices

1. Rotate tokens regularly: Set calendar reminders for annual rotation
2. Use minimum required scopes: Don't grant unnecessary permissions
3. Monitor usage: Enable logging/alerts for API key usage
4. Separate environments: Use different tokens for dev/staging/prod
5. Never commit secrets: Use .gitignore and pre-commit hooks
6. Audit access: Review who has access to 1Password vault quarterly

Token Expiration Schedule

Built with Epic Flowstate