Skip to main content

Using API Key

Learn how to authenticate and use your SimpleCold API key with Bearer Token authentication.

Authentication​

All API requests require authentication using a Bearer token in the Authorization header. Your API key serves as this Bearer token.

Authorization Header Format​

Include your API key in the Authorization header using the following format:

Authorization: Bearer <your-api-key>

Replace <your-api-key> with your actual API key that you generated from the dashboard.

Getting Your API Key​

If you haven't created an API key yet, follow these steps:

  1. Log in to your SimpleCold Dashboard
  2. Navigate to the API Keys section
  3. Click "Create API Key" and copy your key
  4. Store it securely - you can always access and copy it again from the dashboard

API Base URL​

All API endpoints are accessed through the following base URL:

https://api.simplecold.com/api/v1

Validating Your API Key​

Before making API calls, you can verify that your API key is valid using the validate endpoint.

Endpoint: GET /api/v1/api-validation/validate

This endpoint simply checks if your API key is valid and active. It requires no additional parameters.

Request Examples​

Using cURL​

Here's how to validate your API key using cURL:

curl -X GET "https://api.simplecold.com/api/v1/api-validation/validate" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

Success Response (200):

{
  "status": "SUCCESS",
  "payload": {
    "valid": true,
    "message": "API key is valid"
  }
}

Error Response (401):

{
  "status": "FAILURE",
  "message": "Invalid API key"
}

Using JavaScript (Fetch API)​

const apiKey = "YOUR_API_KEY_HERE";

fetch("https://api.simplecold.com/api/v1/api-validation/validate", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
})
  .then((response) => response.json())
  .then((data) => {
    if (data.status === "SUCCESS") {
      console.log("API key is valid!");
    } else {
      console.error("Invalid API key");
    }
  })
  .catch((error) => console.error("Error:", error));

Using Python (requests)​

import requests

api_key = "YOUR_API_KEY_HERE"
url = "https://api.simplecold.com/api/v1/api-validation/validate"

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

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    if data.get("status") == "SUCCESS":
        print("API key is valid!")
else:
    print(f"Error: {response.status_code} - {response.text}")

Error Handling​

Common Error Responses​

401 Unauthorized​

Invalid or Missing API Key:

{
  "status": "FAILURE",
  "message": "Invalid API key"
}

Missing Authorization Header:

{
  "status": "FAILURE",
  "message": "Authorization header is required"
}

Incorrect Format:

{
  "status": "FAILURE",
  "message": "Authorization header must be in format: Bearer <token>"
}

Environment Variables​

Here's how to securely store your API key:

.env file example:​

SIMPLECOLD_API_KEY=your_api_key_here

Using environment variables:​

Node.js:

const apiKey = process.env.SIMPLECOLD_API_KEY;

Python:

import os
api_key = os.getenv("SIMPLECOLD_API_KEY")

Bash:

export SIMPLECOLD_API_KEY="your_api_key_here"

Testing Your API Key​

You can quickly test if your API key is working correctly using the validate endpoint:

curl -X GET "https://api.simplecold.com/api/v1/api-validation/validate" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

A successful response with "valid": true indicates your API key is valid and working.

Additional Resources​