Skip to main content

Authentication

All Matchstra API requests require authentication using an API key. This guide explains how to obtain, use, and manage your API keys securely.

API Key Authentication​

Matchstra uses API key-based authentication. Each request must include your API key in the X-API-Key header.

Header Format​

X-API-Key: your_api_key_here

Obtaining an API Key​

  1. Log in to your Matchstra Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New API Key
  4. Provide a descriptive name (e.g., "Production Server", "Staging Environment")
  5. (Optional) Add IP whitelist restrictions for enhanced security
  6. Click Generate
  7. Copy your API key immediately - it will only be shown once
Important

Your API key is displayed only once upon creation. Store it securely in a password manager or secrets vault. If you lose it, you'll need to generate a new one.

Using Your API Key​

Include your API key in the X-API-Key header with every request.

cURL Example​

curl -X GET https://api.matchstra.ca/api/Screening/list \
  -H "X-API-Key: sk_live_abc123xyz789..."

JavaScript Example​

const apiKey = process.env.MATCHSTRA_API_KEY; // Load from environment variable

const response = await fetch('https://api.matchstra.ca/api/Screening/list', {
  method: 'GET',
  headers: {
    'X-API-Key': apiKey
  }
});

const data = await response.json();

C# Example​

using System.Net.Http;

var client = new HttpClient();
var apiKey = Environment.GetEnvironmentVariable("MATCHSTRA_API_KEY");

client.DefaultRequestHeaders.Add("X-API-Key", apiKey);

var response = await client.GetAsync("https://api.matchstra.ca/api/Screening/list");
var content = await response.Content.ReadAsStringAsync();

Python Example​

import os
import requests

api_key = os.getenv('MATCHSTRA_API_KEY')

headers = {
    'X-API-Key': api_key
}

response = requests.get(
    'https://api.matchstra.ca/api/Screening/list',
    headers=headers
)

data = response.json()

Security Best Practices​

✅ DO​

  • Store keys in environment variables or a secure secrets manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
  • Use different keys for different environments (development, staging, production)
  • Rotate keys periodically (every 90 days recommended)
  • Set IP whitelist restrictions when possible
  • Use HTTPS only - the API rejects HTTP requests
  • Monitor key usage in your dashboard for suspicious activity
  • Revoke compromised keys immediately

❌ DON'T​

  • Never commit keys to version control (Git, SVN, etc.)
  • Never expose keys in client-side code (JavaScript in browsers, mobile apps)
  • Never log API keys in application logs
  • Never share keys via email or messaging
  • Never use production keys in development/testing
  • Never hardcode keys in source code

Key Management​

Rotating Keys​

To rotate your API key:

  1. Generate a new API key in the dashboard
  2. Update your application configuration with the new key
  3. Deploy the updated configuration
  4. Verify the new key works correctly
  5. Revoke the old key

Revoking Keys​

If your API key is compromised:

  1. Immediately revoke it in the dashboard (Settings → API Keys → Revoke)
  2. Generate a new API key
  3. Update all systems using the old key
  4. Review access logs for unauthorized usage

IP Whitelisting​

For added security, restrict API key usage to specific IP addresses:

  1. Edit your API key in the dashboard
  2. Add allowed IP addresses or CIDR ranges
  3. Save changes

Example whitelist:

203.0.113.10
198.51.100.0/24
2001:db8::/32

Authentication Errors​

401 Unauthorized​

Cause: Missing, invalid, or expired API key

Response:

{
  "success": false,
  "message": "Unauthorized. Invalid or missing API key.",
  "data": null,
  "errors": ["Authentication failed"]
}

Solutions:

  • Verify the API key is correctly included in the X-API-Key header
  • Ensure the key hasn't been revoked
  • Check for typos or whitespace in the key
  • Confirm the key is valid for the environment (production vs staging)

403 Forbidden​

Cause: IP address not in whitelist

Response:

{
  "success": false,
  "message": "Forbidden. Request origin not allowed.",
  "data": null,
  "errors": ["IP address not whitelisted"]
}

Solution:

  • Add your IP address to the key's whitelist in the dashboard
  • Use a key without IP restrictions (not recommended for production)

Testing Authentication​

Test your API key with a simple list request:

curl -X GET https://api.matchstra.ca/api/Screening/list \
  -H "X-API-Key: your_api_key_here" \
  -i

Expected Response:

  • Status: 200 OK
  • Body: JSON array of screening results (may be empty)

Error Response:

  • Status: 401 Unauthorized
  • Body: Error message indicating authentication failure

Rate Limiting​

API keys are subject to rate limits based on your license plan. When you exceed the limit, you'll receive a 429 Too Many Requests response.

See the Rate Limits guide for details on handling rate limiting.

Environment-Specific Keys​

Create separate API keys for each environment:

EnvironmentKey NameIP WhitelistUsage
Production"Production API"Production server IPsLive customer traffic
Staging"Staging API"Staging server IPsPre-production testing
Development"Dev API"Developer IPsLocal development
CI/CD"CI Pipeline"CI server IPsAutomated testing

Monitoring​

Monitor your API key usage in the dashboard:

  • Request count - Total API calls made
  • Remaining quota - Available requests in current period
  • Last used - Timestamp of most recent request
  • Error rate - Percentage of failed requests

Set up alerts for:

  • Unusual traffic spikes
  • High error rates
  • Quota approaching limit

FAQ​

Can I use multiple API keys?​

Yes, you can create multiple API keys for different use cases, environments, or applications. Each key is tracked independently.

Do API keys expire?​

API keys do not expire automatically, but we recommend rotating them every 90 days as a security best practice.

Can I regenerate a lost API key?​

No, API keys cannot be retrieved after creation. If you lose a key, you must generate a new one and revoke the old key.

Are there different types of API keys?​

Currently, all API keys have the same permissions and access to all endpoints. Role-based keys are planned for a future release.

Next Steps​