Environments

Matchstra provides multiple environments to support your development lifecycle. This guide explains each environment and how to use them effectively.

Available Environments

Production

Base URL: https://api.matchstra.ca

The production environment is the live system serving real customer data.

Use for:

• Live customer-facing applications
• Production workloads
• Real identity verification and screening

Characteristics:

• ✅ 99.9% uptime SLA
• ✅ Full feature set
• ✅ Real sanctions and PEP data
• ✅ Charges count against your license quota
• ⚠️ Use production API keys only

Example:

curl -X POST https://api.matchstra.ca/api/Screening/screen \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "entityType": "Individual"}'

Staging (Coming Soon)

Base URL: https://staging-api.matchstra.ca (Planned)

A pre-production environment mirroring production for final testing.

Use for:

• Pre-release testing
• Integration testing
• Load testing
• Reproducing production issues

Characteristics:

• Mirrors production configuration
• Test data only (no real PII)
• Separate API keys
• Does not count against production quota

Sandbox (Coming Soon)

Base URL: https://sandbox-api.matchstra.ca (Planned)

A fully isolated testing environment with mock data.

Use for:

• Development and prototyping
• CI/CD automated tests
• Learning and experimentation
• Demo applications

Characteristics:

• Mock responses (predictable test data)
• Unlimited requests (no quota limits)
• No real screening or verification
• Separate API keys

Environment Selection

Choose the appropriate environment based on your use case:

Use Case	Environment	API Key Type
Live customer traffic	Production	sk_live_...
Pre-deployment QA	Staging	sk_staging_...
Development	Sandbox	sk_sandbox_...
CI/CD tests	Sandbox	sk_sandbox_...
Demos	Sandbox	sk_sandbox_...

Configuration Examples

Environment Variables

Store environment-specific configuration in environment variables:

# .env.production
MATCHSTRA_API_URL=https://api.matchstra.ca
MATCHSTRA_API_KEY=sk_live_abc123...

# .env.staging
MATCHSTRA_API_URL=https://staging-api.matchstra.ca
MATCHSTRA_API_KEY=sk_staging_xyz789...

# .env.development
MATCHSTRA_API_URL=https://sandbox-api.matchstra.ca
MATCHSTRA_API_KEY=sk_sandbox_test123...

JavaScript/Node.js

// config.js
const config = {
  production: {
    apiUrl: 'https://api.matchstra.ca',
    apiKey: process.env.MATCHSTRA_API_KEY_PROD
  },
  staging: {
    apiUrl: 'https://staging-api.matchstra.ca',
    apiKey: process.env.MATCHSTRA_API_KEY_STAGING
  },
  development: {
    apiUrl: 'https://sandbox-api.matchstra.ca',
    apiKey: process.env.MATCHSTRA_API_KEY_SANDBOX
  }
};

const env = process.env.NODE_ENV || 'development';
module.exports = config[env];

C# (.NET)

// appsettings.json (per environment)
{
  "Matchstra": {
    "ApiUrl": "https://api.matchstra.ca",
    "ApiKey": "sk_live_abc123..."
  }
}

// Usage in code
public class MatchstraConfig
{
    public string ApiUrl { get; set; }
    public string ApiKey { get; set; }
}

// Startup.cs or Program.cs
services.Configure<MatchstraConfig>(
    Configuration.GetSection("Matchstra")
);

Python

# config.py
import os

ENVIRONMENTS = {
    'production': {
        'api_url': 'https://api.matchstra.ca',
        'api_key': os.getenv('MATCHSTRA_API_KEY_PROD')
    },
    'staging': {
        'api_url': 'https://staging-api.matchstra.ca',
        'api_key': os.getenv('MATCHSTRA_API_KEY_STAGING')
    },
    'development': {
        'api_url': 'https://sandbox-api.matchstra.ca',
        'api_key': os.getenv('MATCHSTRA_API_KEY_SANDBOX')
    }
}

ENV = os.getenv('ENVIRONMENT', 'development')
config = ENVIRONMENTS[ENV]

API Compatibility

All environments share the same API contract:

• Identical endpoint paths
• Same request/response schemas
• Consistent error codes
• Matching HTTP status codes

This ensures code written for one environment works seamlessly in others (with only configuration changes).

Testing Across Environments

Development Workflow

1. Develop in sandbox with mock data
2. Test in staging with production-like conditions
3. Deploy to production with confidence

Sample Test Script

// test-all-environments.js
const environments = ['sandbox', 'staging', 'production'];

for (const env of environments) {
  const config = getConfigForEnv(env);
  
  console.log(`Testing ${env}...`);
  
  const response = await fetch(`${config.apiUrl}/api/Screening/screen`, {
    method: 'POST',
    headers: {
      'X-API-Key': config.apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Test User',
      entityType: 'Individual'
    })
  });
  
  const data = await response.json();
  console.log(`${env} result:`, data.success ? '✅' : '❌');
}

Environment-Specific Behaviors

Production

• Data: Real PEP and sanctions databases
• Quota: Counted against your license
• Images: Stored securely for 90 days
• Logs: Detailed audit logs maintained

Staging (Planned)

• Data: Anonymized test data resembling production
• Quota: Separate allowance (e.g., 1,000 requests/month)
• Images: Stored for 7 days
• Logs: Available for debugging

Sandbox (Planned)

• Data: Static mock responses
• Quota: Unlimited
• Images: Not stored
• Logs: Basic logging only

Troubleshooting

Wrong Environment

Symptom: API calls fail with 401 or unexpected responses

Cause: Using the wrong API key for the environment

Solution:

• Verify the API key prefix matches the environment (sk_live_, sk_staging_, sk_sandbox_)
• Check your configuration is loading the correct environment variables
• Confirm the base URL matches the intended environment

Cross-Environment Key Usage

API keys are environment-specific and cannot be used across environments:

Key Type	Valid Environments
sk_live_...	Production only
sk_staging_...	Staging only
sk_sandbox_...	Sandbox only

Best Practices

1. Separate Keys Per Environment

Never reuse API keys across environments. Create dedicated keys for each.

2. Automate Environment Switching

Use environment variables or configuration files to switch environments automatically based on your deployment target.

3. Test in Staging First

Always test changes in staging before deploying to production.

4. Monitor All Environments

Set up monitoring and alerting for all environments to catch issues early.

5. Document Environment Setup

Maintain clear documentation on how to configure and access each environment for your team.

Migration Path

When new environments launch, we'll provide:

1. Migration guides with step-by-step instructions
2. Code examples for each supported language
3. Test scripts to verify environment setup
4. Support during the transition period

FAQ

Is there a free sandbox environment?

Sandbox environment is planned and will be free with unlimited requests for testing and development.

Can I create custom environments?

Enterprise customers can request dedicated environments. Contact [email protected] for details.

How do I access staging?

Staging access will be available soon. Subscribe to our changelog for updates.

Do sandbox requests count against my quota?

No, sandbox requests (when available) will not count against your production quota.

Next Steps

• Make your first API call using the production environment
• Learn about rate limits to optimize usage
• Set up error handling for production resilience