🔑 How to Authenticate

Step 1: Obtain Your API Key

Contact your account manager at integrations@365finance.co.uk to request an API key. You will receive:

A unique API key (64-character hexadecimal string)
Access to the staging environment for testing
Documentation and integration support

Step 2: Include API Key in Request Headers

Add the X-API-Key header to every API request:

GET /cashadvances?startDate=2025-11-01&endDate=2025-12-01 HTTP/1.1
Host: staging-api.365finance.co.uk
X-API-Key: your-api-key-here

Important: The API key must be included in the X-API-Key header (case-sensitive) for all requests.

💻 Code Examples

cURL

curl -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: your-api-key-here"

JavaScript / Node.js

const response = await fetch(
  'https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01',
  {
    headers: {
      'X-API-Key': 'your-api-key-here'
    }
  }
);

const data = await response.json();
console.log(data);

Python

import requests

headers = {
    'X-API-Key': 'your-api-key-here'
}

params = {
    'startDate': '2025-11-01',
    'endDate': '2025-12-01'
}

response = requests.get(
    'https://staging-api.365finance.co.uk/cashadvances',
    headers=headers,
    params=params
)

data = response.json()
print(data)

PHP

<?php
$apiKey = 'your-api-key-here';
$url = 'https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-API-Key: ' . $apiKey
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

curl_close($ch);
print_r($data);
?>

C# / .NET

using System;
using System.Net.Http;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your-api-key-here");

var response = await client.GetAsync(
    "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01"
);

var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);

Java

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01"))
    .header("X-API-Key", "your-api-key-here")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

🔒 Security Best Practices

Keep Your API Key Secure

Never commit to version control - Add your API key to .gitignore or use environment variables
Don't expose in client-side code - API keys should only be used in server-side applications
Use environment variables - Store your API key in environment variables, not hardcoded in your application

Example (.env file):

API_KEY=your-api-key-here
API_URL=https://staging-api.365finance.co.uk

Rotate Keys Regularly

Request new API keys periodically for enhanced security. Contact integrations@365finance.co.uk to rotate your keys.

Use HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected. This is enforced by the API Gateway.

Monitor Usage

Track your API usage and report any suspicious activity to integrations@365finance.co.uk immediately.

IP Whitelisting (Optional)

For additional security, you can whitelist specific IP addresses. Contact integrations@365finance.co.uk to configure IP restrictions for your API key.

Benefits:

Only requests from whitelisted IPs will be accepted
Additional layer of security beyond API key
Ideal for production environments with static IPs

⚠️ Authentication Errors

401 Unauthorized - Missing API Key

Cause: The X-API-Key header is missing from your request.

Response:

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authentication required",
    "details": "API key is required. Please include X-API-Key header in your request.",
    "requestId": "req-abc-123",
    "timestamp": "2026-01-28T14:55:00.000Z"
  }
}

Solution:

Ensure you're including the X-API-Key header in your request
Check for typos in the header name (it's case-sensitive)
Verify your HTTP client is sending headers correctly

403 Forbidden - Invalid API Key

Cause: The API key provided is invalid, expired, or has been deactivated.

Response:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Access denied",
    "details": "The provided API key is invalid or has been deactivated. Please contact support.",
    "requestId": "req-abc-124",
    "timestamp": "2026-01-28T14:55:00.000Z"
  }
}

Solution:

Verify you're using the correct API key
Check if your API key has been deactivated
Contact integrations@365finance.co.uk to verify your API key status or request a new one

🧪 Testing Your Authentication

Staging Environment

Test your API key in the staging environment before going live:

curl -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: your-staging-api-key"

Expected Success Response (200 OK)

{
  "RequestId": "req-abc-123",
  "TotalRecords": 5,
  "Timestamp": "2026-01-28T14:55:00.000Z",
  "CashAdvances": [
    {
      "FundedDate": "2025-11-20",
      "FundedAmount": 15000.00,
      "CustomerReference": "CUST-001",
      "CashAdvanceNumber": "CA-2025-001",
      "BrokerReference": "BRK-001",
      "FactorRate": 1.15,
      "TotalRepayment": 17250.00
    }
  ]
}

Verify Authentication is Working

Test 1: Valid API Key

# Should return 200 OK with data
curl -i -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: your-valid-api-key"

Test 2: Missing API Key

# Should return 401 Unauthorized
curl -i -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01"

Test 3: Invalid API Key

# Should return 403 Forbidden
curl -i -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: invalid-key-12345"

🌐 Environments

Staging

URL: https://staging-api.365finance.co.uk

Purpose:

Testing and development
Safe environment for integration testing
Uses Salesforce sandbox data
No impact on production data

Use staging for:

Initial API integration
Testing error handling
Validating request/response formats
Performance testing

Production

URL: https://api.365finance.co.uk

Purpose:

Live production data
Real customer transactions
Production Salesforce instance

Requirements:

Separate production API key
Completed staging testing
Approved by your account manager

📊 Data Filtering

Your API key is automatically linked to your partner/broker ID. All API responses are automatically filtered to show only data relevant to your organization.

What this means:

You only see cash advances for your brokerage
No need to specify partner ID in requests
Data isolation is enforced at the API level
Secure multi-tenant architecture

Example: If your partner ID is BRK-001, all API calls will only return cash advances where you are the broker, regardless of query parameters.

🔄 API Key Lifecycle

Requesting a New API Key

Contact integrations@365finance.co.uk
Provide your company name and contact information
Receive your API key via secure channel

Rotating API Keys

When to rotate:

Suspected key compromise
Employee departure
Regular security maintenance (recommended quarterly)
Moving from staging to production

How to rotate:

Request new API key from integrations@365finance.co.uk
Update your application with new key
Test with new key in staging
Deploy to production
Notify support to deactivate old key

Tip: Request the new key before deactivating the old one to avoid downtime.

Deactivating API Keys

Contact integrations@365finance.co.uk to deactivate:

Compromised keys
Unused keys
Keys for terminated integrations

Deactivated keys will immediately return 403 Forbidden errors.

📞 Support & Troubleshooting

Common Issues

Issue: "I'm getting 401 errors even with a valid API key"

Solutions:

Verify header name is exactly X-API-Key (case-sensitive)
Check for extra spaces in the API key value
Ensure you're not accidentally encoding the header
Test with cURL first to isolate application issues

Issue: "API key works in staging but not production"

Solutions:

Verify you're using the production API key (not staging key)
Confirm production key has been activated
Check if IP whitelisting is enabled for production

Issue: "Getting 403 errors after IP change"

Solutions:

Your IP address may have changed (dynamic IP)
Contact support to update IP whitelist
Consider using a static IP or VPN for production

Request ID for Support

Every API response includes a RequestId field. Always include this when contacting support:

{
  "RequestId": "req-abc-123",
  ...
}

This helps our support team quickly locate your request in our logs.

Contact Support

Email: integrations@365finance.co.uk

Include in your support request:

Your company name
API key (last 8 characters only)
RequestId from error response
Timestamp of the issue
Full error message
Steps to reproduce

✅ Quick Start Checklist

Last Updated: January 28, 2026
API Version: 2.0.0
Support: integrations@365finance.co.uk