Skip to main content
The ENVIRONMENT_API_KEY is a credential used to authenticate requests between the Synth training backend and your task apps. It’s separate from SYNTH_API_KEY (which authenticates with the Synth backend) and is scoped to your organization.

​
Purpose

ENVIRONMENT_API_KEY serves as the authentication token that:
  1. Authenticates backend-to-task-app requests: When the Synth training backend makes requests to your task app endpoints (like /rollout, /health, /task_info), it includes this key in the X-API-Key header.
  2. Secures task app endpoints: Your task app validates incoming requests by comparing the X-API-Key header against the ENVIRONMENT_API_KEY environment variable set in the task app’s runtime environment.
  3. Enables organization-scoped access: Each organization has its own ENVIRONMENT_API_KEY stored encrypted in the backend database, ensuring that training jobs can only access task apps belonging to the same organization.

​
How It Works

​
Storage and Retrieval

The backend stores ENVIRONMENT_API_KEY credentials in the customer_credentials table with credential_type = 'ENVIRONMENT_API_KEY'. Each credential is:
  • Encrypted using sealed-box encryption (NaCl) with organization-specific public/private key pairs
  • Scoped to an organization via org_id
  • Marked as active via credential_metadata.is_active flag
  • Optionally scoped to an environment via credential_metadata.env (e.g., “dev”, “prod”)
When a training job needs to communicate with a task app, the backend:
  1. Retrieves the active ENVIRONMENT_API_KEY for the organization from the database
  2. Decrypts it using the organization’s private key
  3. Includes it in HTTP requests to the task app as the X-API-Key header

​
Task App Validation

Task apps validate incoming requests by:
  1. Reading ENVIRONMENT_API_KEY from their runtime environment variables
  2. Comparing it against the X-API-Key header (or Authorization: Bearer header) in incoming requests
  3. Returning 401 Unauthorized if the keys don’t match, or 503 Service Unavailable if ENVIRONMENT_API_KEY is not configured in the task app environment
The SDK provides normalize_environment_api_key() and is_api_key_header_authorized() functions (from synth_ai.task.auth) to handle this validation consistently.

​
Client-Side Usage

When using the CLI or SDK locally:
  • Fetch credentials: Run uvx synth-ai setup to retrieve both SYNTH_API_KEY and ENVIRONMENT_API_KEY from your Synth account
  • Store locally: The CLI writes these to .env files and ~/.synth-ai/config.json
  • Use for health checks: The CLI uses ENVIRONMENT_API_KEY to verify task app health before submitting training jobs
  • Pass to task apps: When deploying task apps, ensure ENVIRONMENT_API_KEY is available in the deployment environment (via environment variables, Modal secrets, etc.)

​
When It’s Required

ENVIRONMENT_API_KEY is required for:
  • Reinforcement Learning training: The backend needs it to call /rollout endpoints during training
  • Prompt Optimization (GEPA/MIPRO): The orchestrator uses it to evaluate prompt candidates via /rollout
  • Task app health checks: The CLI validates task app availability before job submission
  • Periodic evaluation: During RL training, periodic evaluation rollouts require ENVIRONMENT_API_KEY to be available in the trainer environment

​
Common Issues

​
Missing Active Key

If the backend cannot find an active ENVIRONMENT_API_KEY for your organization, you’ll see errors like: 
Missing active ENVIRONMENT_API_KEY
No rollout key is active for this organization
Solution: Ensure the ENVIRONMENT_API_KEY you used to start your task app is uploaded to the same organization as your SYNTH_API_KEY. Run synth-ai setup to fetch and store both credentials.

​
Task App Authentication Failures

If your task app returns 401 Unauthorized or 503 Service Unavailable:
  • 503: The task app is missing ENVIRONMENT_API_KEY in its environment. Ensure it’s set when deploying (via Modal secrets, environment variables, etc.)
  • 401: The key in the request header doesn’t match the task app’s ENVIRONMENT_API_KEY. Verify both are from the same organization and the task app is using the correct key

​
Key Mismatch Between Backend and Task App

The ENVIRONMENT_API_KEY used by the backend must match the one configured in your task app. If they differ:
  1. The backend retrieves the key from the organization’s stored credentials
  2. Your task app reads it from its environment variable
  3. Both must be the same value for authentication to succeed
Ensure you’ve uploaded the same ENVIRONMENT_API_KEY to your Synth organization that you’re using in your task app deployment.

​
Security Considerations

  • Organization isolation: Each organization’s ENVIRONMENT_API_KEY is encrypted and stored separately, preventing cross-organization access
  • Encryption at rest: Keys are stored encrypted in the database using sealed-box encryption
  • Environment scoping: Keys can be scoped to specific environments (dev/prod) to prevent accidental cross-environment access
  • Active flag: Only active credentials are used, allowing you to rotate keys by deactivating old ones and creating new ones
  • SYNTH_API_KEY: Authenticates with the Synth backend API (different from ENVIRONMENT_API_KEY)
  • Task App Authentication: See task app documentation for details on implementing authentication endpoints
  • Credential Management: Use synth-ai setup or the backend API to manage organization credentials