Documentation

Copy page

Authentication

All API requests require authentication using an API key. This page explains how to obtain and use your API key securely.

---

How Authentication Works

The SalesCaddie API uses API Key authentication. Your API key must be included in the Authorization header of every request using the Bearer authentication scheme.

Request Format

Code
 
Authorization: Bearer YOUR_API_KEY

Complete Example

Code
 
curl -X POST https://api.salescaddie.dev/v1/deals \
  -H "Authorization: Bearer zpka_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

---

Getting Your API Key

For Production

Please reach out to us at [email protected] to receive your production API credentials. We'll provide you with:

• Your unique API key (starts with zpka_)
• Your tenant ID
• Access to this developer portal

Managing Your Keys (Coming Soon!)

---

Security Best Practices

⚠️ Keep Your API Key Secret

DO:

• ✅ Store keys in environment variables
• ✅ Use secrets management systems (AWS Secrets Manager, HashiCorp Vault, etc.)
• ✅ Rotate keys regularly
• ✅ Use different keys for different environments (staging vs production)

DON'T:

• ❌ Commit keys to version control (Git, SVN, etc.)
• ❌ Share keys via email or chat
• ❌ Use production keys in staging/development
• ❌ Hardcode keys in your application code

Authentication Errors

If your API key is missing, invalid, or expired, you'll receive a 401 Unauthorized response:

Code
 
{
  "type": "https://httpstatuses.com/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key",
  "instance": "/v1/deals",
  "trace": {
    "timestamp": "2025-11-13T22:41:48.080Z",
    "requestId": "xyz789-request-id",
    "buildId": "5333d1e2-475a-4ae6-a66a-0105505b3a6f",
    "rayId": "99e1c752dfef2ed3"
  }
}

---

Environment Variables Example

Here's how to securely store and use your API key in different languages:

Node.js

.env file (never commit this!):

Code
 
SALESCADDIE_API_KEY=zpka_1234567890abcdef

In your code:

Code
 
require("dotenv").config()
const apiKey = process.env.SALESCADDIE_API_KEY

fetch("https://api.salescaddie.dev/v1/deals", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    /* your data */
  }),
})

Python

.env file (never commit this!):

Code
 
SALESCADDIE_API_KEY=zpka_1234567890abcdef

In your code:

Code
 
import os
from dotenv import load_dotenv
import requests

load_dotenv()
api_key = os.getenv('SALESCADDIE_API_KEY')

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.salescaddie.dev/v1/deals',
    headers=headers,
    json={ /* your data */ }
)

PHP

.env file (never commit this!):

Code
 
SALESCADDIE_API_KEY=zpka_1234567890abcdef

In your code:

Code
 
<?php
// Load from environment
$apiKey = getenv('SALESCADDIE_API_KEY');

$ch = curl_init('https://api.salescaddie.dev/v1/deals');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ /* your data */ ]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>

---

Next Steps

→ Learn about Core Concepts like idempotency

→ Explore the API Reference for all available endpoints

→ Need help? Check out Support