Environments

Turquoise provides three isolated environments for development, testing, and production workloads.

Environment Overview

Feature	Sandbox	Staging	Production
Base URL	sandbox.api.turquoise.health/tpa-api/v1	staging.api.turquoise.health/tpa-api/v1	api.turquoise.health/tpa-api/v1
Data	Test data only	Real-world test data	Live healthcare data
Payments	Simulated	Simulated	Real (Stripe)
Auth	API Key	API Key	OAuth 2.0 + mTLS
Rate Limit	Unlimited	200 req/min	100 req/min (default)
Data Retention	7 days	30 days	Indefinite
SLA	Best effort	99.5%	99.9%
Cost	Free	Free	Standard pricing

Sandbox Environment

Purpose

Sandbox is ideal for initial development and testing. All data is synthetic, and no real payments occur.

Base URL

https://sandbox.api.turquoise.health/tpa-api/v1

Features

• Test Data: Pre-configured Sharp HealthCare provider and plan
• Reset: Daily reset at midnight UTC
• Webhooks: Simulated webhook delivery
• Debugging: Enhanced logging and diagnostic endpoints
• Rate Limits: No practical limits (1000+ req/min)

Test Data Available

# Get list of available test resources
curl -X GET \
  https://sandbox.api.turquoise.health/tpa-api/v1/test-fixtures \
  -H "X-API-Key: $TURQUOISE_API_KEY"

Response includes:

{
  "providers": [
    {
      "npi": "1234567890",
      "name": "Sharp HealthCare",
      "specialties": ["gastroenterology"]
    }
  ],
  "plans": [
    {
      "id": "SHARP-HMO-2024",
      "name": "Sharp Health Plan",
      "contracts": [
        {
          "service_code": "43235",
          "description": "EGD",
          "negotiated_rate": 1200.00
        }
      ]
    }
  ],
  "members": [
    {
      "member_id": "SHP00123456",
      "plan_id": "SHARP-HMO-2024",
      "name": "Demo Member",
      "effective_date": "2024-01-01"
    }
  ]
}

Example Workflows

# Contract Lookup (Blind)
curl -X POST \
  https://sandbox.api.turquoise.health/tpa-api/v1/contracts/lookup \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -d '{
    "provider_npi": "1234567890",
    "plan_id": "SHARP-HMO-2024",
    "service_code": "43235"
  }'

# Claim Submission
curl -X POST \
  https://sandbox.api.turquoise.health/tpa-api/v1/claims/submit \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d '{...}'

# Settlement Polling
curl -X GET \
  https://sandbox.api.turquoise.health/tpa-api/v1/settlements/DEMO-CLM-001 \
  -H "X-API-Key: $TURQUOISE_API_KEY"

warning

Sandbox data resets daily at 00:00 UTC. Do not rely on persistent state.

Staging Environment

Purpose

Staging mirrors production behavior with real-world test data but no live payment processing. Use before production rollout.

Base URL

https://staging.api.turquoise.health/tpa-api/v1

Features

• Test Data: Realistic healthcare scenarios (multiple providers, plans, members)
• Realistic Behavior: Mirrors production response times and behavior
• Limited Reset: Data retained for 30 days (allows testing reconciliation flows)
• Real Webhooks: Actual webhook delivery (to your test endpoint)
• Payment Simulation: Stripe test mode (no actual charges)
• Rate Limits: 200 requests/minute

Testing Scenarios

# Test batch claim processing (TPA workflow)
curl -X POST \
  https://staging.api.turquoise.health/tpa-api/v1/claims/batch-submit \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d '[
    {"resourceType": "Claim", ...},
    {"resourceType": "Claim", ...}
  ]'

# Test settlement webhook delivery
curl -X POST \
  https://api.turquoise.health/webhooks/subscribe \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -d '{
    "url": "https://your-tpa.com/webhooks/settlements",
    "events": ["settlement.completed", "adjustment.initiated"]
  }'

info

Before moving to production, test webhook delivery, error handling, and reconciliation processes in staging.

Production Environment

Purpose

Production is your live environment serving real claims and processing actual payments through Stripe.

Base URL

https://api.turquoise.health/tpa-api/v1

Requirements

• Authentication: OAuth 2.0 + mTLS certificates (required)
• TLS: TLS 1.3 minimum (TLS 1.2 available for legacy systems)
• Rate Limits: 100 requests/minute (configurable for enterprise)
• Monitoring: Integration with your monitoring stack required

Features

• Real Data: Live member, provider, and plan data
• Real Payments: Stripe Connect processes actual disbursements
• High Availability: Multi-region deployment with 99.9% uptime SLA
• Audit Logging: Immutable audit trail for compliance
• Automatic Scaling: Handles peak transaction volumes

Deployment Checklist

• OAuth 2.0 + mTLS certificates installed
• Rate limiting strategy implemented
• Error handling and retry logic tested
• Webhook endpoints secured and monitoring active
• Data encryption in transit (TLS 1.3) and at rest
• Monitoring dashboards set up
• Incident response plan documented
• Compliance review complete (HIPAA, state regulations)

Monitoring Production

# Health check
curl -X GET \
  https://api.turquoise.health/tpa-api/v1/health \
  --cert client.crt --key client.key \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Check API status
curl -X GET \
  https://status.turquoise.health/api/v1/status

# View rate limit status
curl -X GET \
  https://api.turquoise.health/tpa-api/v1/rate-limit-status \
  --cert client.crt --key client.key \
  -H "Authorization: Bearer $ACCESS_TOKEN"

warning

Production API key rotation requires careful planning. Coordinate with Turquoise support to ensure zero downtime.

Migrating Between Environments

Sandbox → Staging

# 1. Update API endpoints
export TURQUOISE_API_URL="https://staging.api.turquoise.health/tpa-api/v1"

# 2. Request staging API key
# Contact support@turquoise.health

# 3. Export new credentials
export TURQUOISE_API_KEY="sk_stage_..."

# 4. Run integration tests
npm run test:integration

# 5. Load test data
curl -X POST \
  https://staging.api.turquoise.health/tpa-api/v1/test-fixtures/load \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -d '{"fixture": "multi-provider-scenario"}'

Staging → Production

# 1. Obtain mTLS certificates
# Contact support@turquoise.health

# 2. Update configuration
export TURQUOISE_API_URL="https://api.turquoise.health/tpa-api/v1"
export TURQUOISE_CERT_PATH="./client.crt"
export TURQUOISE_KEY_PATH="./client.key"
export TURQUOISE_CA_PATH="./ca.crt"

# 3. Verify OAuth token flow
./scripts/verify-oauth.sh

# 4. Canary deployment (5% traffic)
kubectl set image deployment/tpa-client tpa-client=your-image:prod --record

# 5. Monitor metrics for 2 hours
# Check dashboard at https://monitoring.turquoise.health

# 6. Full rollout
kubectl set image deployment/tpa-client tpa-client=your-image:prod --record

Environment-Specific Configuration

Python Example

import os
from turquoise import TurquoiseClient

environment = os.getenv('TURQUOISE_ENV', 'sandbox')

if environment == 'production':
    client = TurquoiseClient(
        base_url='https://api.turquoise.health/tpa-api/v1',
        cert_path='./client.crt',
        key_path='./client.key',
        ca_path='./ca.crt',
        auth_type='oauth2_mtls'
    )
else:
    client = TurquoiseClient(
        base_url=f'https://{environment}.api.turquoise.health/tpa-api/v1',
        api_key=os.getenv('TURQUOISE_API_KEY'),
        auth_type='api_key'
    )

Node.js Example

const TurquoiseClient = require('@turquoise/tpa-sdk');

const config = {
  sandbox: {
    baseUrl: 'https://sandbox.api.turquoise.health/tpa-api/v1',
    authType: 'api_key',
    apiKey: process.env.TURQUOISE_API_KEY
  },
  production: {
    baseUrl: 'https://api.turquoise.health/tpa-api/v1',
    authType: 'oauth2_mtls',
    certPath: './client.crt',
    keyPath: './client.key',
    caPath: './ca.crt'
  }
};

const client = new TurquoiseClient(config[process.env.NODE_ENV || 'sandbox']);

Support

Environment	Support Channel	Response Time
Sandbox	Email	24 hours
Staging	Email / Slack	4 hours
Production	Phone / Slack / Email	1 hour

Contact support@turquoise.health or call 1-800-TURQUOISE.

Next Steps

• Quickstart in Sandbox
• Authentication Setup
• TPA Integration Guide