Skip to main content

Authentication

All API requests require authentication using a valid API key.

For launch there is no domain or IP whitelisting. You can call the API from anywhere (production, staging, localhost, preview deploys, Postman, etc.).  

When we open the API to more partners in 2026 we plan to add a domain allow-list (max 10 domains you control yourself).

API Keys​

Email partners@finmatch.io for your API key. Treat your API keys like passwords - never commit them to source control or expose them in client-side code.

Making Authenticated Requests​

Include your API key in the Authorization header:

Authorization: Bearer sk_apikey

Example Request​

curl -X POST https://api.finmatch.io/v1/finance-quote \
  -H "Authorization: Bearer sk_apikey" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Example with JavaScript​

const response = await fetch('https://api.finmatch.io/v1/finance-quote', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_apikey',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchant_id: 'M000100',
    partner_id: 'P000001',
    loan_amount: 5000.00,
    merchant_finance_url: 'https://www.xyzsolar.co.uk/finance'
  })
});

const data = await response.json();

Security Best Practices​

1. Keep Keys Secure​

  • Never expose API keys in client-side code
  • Use environment variables or secret management systems

2. Server-Side Only​

Make API calls from your backend server, not from browsers or mobile apps.

3. Use HTTPS​

Always make requests over HTTPS. HTTP requests will be rejected.

Rate Limiting​

API keys are subject to rate limits:

  • 100 requests per minute per API key
  • Rate limit headers included in responses
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Error Responses​

401 Unauthorized​

Missing or invalid API key:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid authorization header. Use: Authorization: Bearer sk_apikey"
  }
}

429 Too Many Requests​

Rate limit exceeded:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Maximum 100 requests per minute."
  }
}

Getting Help​

Need an API key? Email partners@finmatch.io.

Issues with authentication? Contact us.