Auth API

Authenticate API requests to CSVBox using a secure header-based scheme that validates both your API Key and Secret API Key.

Overview

CSVBox requires two authentication headers for all protected API requests:

WARNING

Always send requests over HTTPS.
Never include keys in query parameters or expose them in browser-side code.
Store keys securely in your server environment.

Finding Your Keys

Log in to CSVBox Dashboard.
Click your profile name → Profile → API Keys tab.
Copy your API and Secret keys.
If keys are missing or compromised, click Regenerate Key.

Authentication Flow

Client sends a request to a protected endpoint with both headers.
CSVBox validates:
- The API key exists and is active.
- The Secret key matches the same account.
If valid → returns 200 OK and requested data.
If invalid → returns an appropriate error code.

Endpoint

Verify Credentials API

POST https://api.csvbox.io/1.1/auth

You can verify your credentials using this endpoint.

Headers

Name

Value

content-type

application/json

x-csvbox-api-key

<your-api-key>

x-csvbox-secret-api-key

<your-secret-api-key>

Body

Name

Type

Description

name

string

Name of the user

age

number

Age of the user

Response

{
  "message": "successfully authenticated",
  "data": {
    "name": "John Doe",
    "email": "abc@xyz.com",
    "profile_photo_url": "<url_string>"
  }
}

❌ Error Responses

Status

Error

Example

400 Bad Request

Missing or malformed headers

{ "errors": "bad_request" }

401 Unauthorized

Invalid credentials

{ "errors": "invalid_credentials" }

403 Forbidden

Account lacks permission

{ "errors": "forbidden"}

429 Too Many Requests

Rate limit exceeded

{ "errors": "rate_limited"}

Security Best Practices

Use HTTPS (TLS) exclusively.
Send keys in headers, never in URLs.
Mask secret fields in your UI (type="password").
Do not log raw keys—mask them (e.g., ****abcd).
Rotate and revoke keys regularly via dashboard.

Store credentials as environment variables:

CSVBOX_API_KEY=your_api_key
CSVBOX_SECRET_API_KEY=your_secret_key

For browser apps, always proxy API requests through your backend.

Example Requests

curl -i -X GET "https://api.csvbox.io/1.1/auth" \
  -H "Accept: application/json" \
  -H "x-csvbox-api-key: <your-api-key>" \
  -H "x-csvbox-secret-api-key: <your-secret-key>"

$.ajax({
  url: "https://api.csvbox.io/1.1/auth",
  headers: {
    "x-csvbox-api-key": "<api-key>",
    "x-csvbox-secret-api-key": "<secret-key>"
  },
  success: (data) => console.log("Authenticated:", data),
  error: (xhr) => console.error("Error:", xhr.status, xhr.responseJSON)
});

<?php
$ch = curl_init("https://api.csvbox.io/1.1/auth");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Accept: application/json",
  "x-csvbox-api-key: " . getenv('CSVBOX_API_KEY'),
  "x-csvbox-secret-api-key: " . getenv('CSVBOX_SECRET_API_KEY')
]);

$response = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code === 200) {
  echo "Authenticated successfully:\n" . $response;
} else {
  echo "Authentication failed (HTTP $code):\n" . $response;
}

import axios from "axios";

async function testAuth() {
  try {
    const res = await axios.get("https://api.csvbox.io/1.1/auth", {
      headers: {
        "Accept": "application/json",
        "x-csvbox-api-key": process.env.CSVBOX_API_KEY,
        "x-csvbox-secret-api-key": process.env.CSVBOX_SECRET_API_KEY
      },
    });
    console.log("Authenticated:", res.data);
  } catch (err) {
    console.error("Error:", err.response?.data || err.message);
  }
}

testAuth();

Never expose your secret keys in browser-side code.

FAQ

Can I send only the API key? No. Both headers are required for authentication.

Can I use query parameters for keys? No. Query-based authentication is disabled for security reasons.

Where should I store my keys? Store them server-side in environment variables or a secrets manager.

I lost my secret key. What now? Regenerate it from the API Keys page.

Troubleshooting & Support

If authentication fails:

Verify exact header names (x-csvbox-api-key, x-csvbox-secret-api-key).
Ensure your account and keys are active.
Confirm you’re using HTTPS.
If still failing, contact support with your request ID or timestamp.

Summary

Topic

Details

Method

Header-based (API Key + Secret Key)

Headers

x-csvbox-api-key, x-csvbox-secret-api-key

Protocol

HTTPS only

Auth Type

Server-to-server

Test Endpoint

GET https://api.csvbox.io/1.1/auth

Use this endpoint to verify your integration before making any other CSVBox API calls.

PreviousEnvironment Variables NextSheet API

Last updated 8 months ago