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

1. Log in to CSVBox Dashboard.

2. Click your profile name → Profile → API Keys tab.

3. Copy your API and Secret keys.

4. If keys are missing or compromised, click Regenerate Key.

---

Authentication Flow

1. Client sends a request to a protected endpoint with both headers.

2. CSVBox validates:

   • The API key exists and is active.

   • The Secret key matches the same account.

3. If valid → returns 200 OK and requested data.

4. 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

200 OK

{
  "message": "successfully authenticated",
  "data": {
    "name": "John Doe",
    "email": "[email protected]",
    "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

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>"

jQuery (for testing)

PHP

NodeJS

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:

1. Verify exact header names (x-csvbox-api-key, x-csvbox-secret-api-key).

2. Ensure your account and keys are active.

3. Confirm you’re using HTTPS.

4. 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.