Authentication

API Key Authentication

Use API keys for server-to-server authentication. Include your key in the Authorization header with Bearer prefix.

// Request header
Authorization: Bearer fc_live_xxxxxxxxxxxxxxxx

// Generate HMAC signature
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(timestamp + method + path + body)
  .digest('hex');

// Include signature header
X-FreshCredit-Signature: {signature}
X-FreshCredit-Timestamp: {unix_timestamp}

OAuth 2.0

For user-delegated access, use OAuth 2.0 authorization code flow. Users authorize your application to access their FreshCredit data.

// Step 1: Redirect user to authorization endpoint
https://app.freshcredit.com/oauth/authorize?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=https://your-app.com/callback&
  scope=blockid:read blockscore:read&
  state=random_state_string

// Step 2: Exchange code for access token
POST https://api.freshcredit.com/v1/oauth/token
{
  "grant_type": "authorization_code",
  "code": "auth_code_from_callback",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://your-app.com/callback"
}

All webhooks include a signature header. Verify signatures to ensure requests originate from FreshCredit.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhooks/freshcredit', (req, res) => {
  const signature = req.headers['x-freshcredit-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  handleWebhook(req.body);
  res.status(200).send('OK');
});