# Auth API

### Overview

CSVBox requires **two authentication headers** for all protected API requests:

{% hint style="info" %}
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.
  {% endhint %}

***

### Finding Your Keys

1. Log in to [CSVBox Dashboard](https://app.csvbox.io/).
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

<mark style="color:green;">`POST`</mark> `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**

{% tabs %}
{% tab title="200 OK" %}

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

{% endtab %}
{% endtabs %}

#### ❌ 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:

  ```bash
  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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="jQuery (for testing)" %}

```javascript
$.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)
});
```

{% endtab %}

{% tab title="PHP" %}

```php
<?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;
}
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
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();
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Never expose your secret keys in browser-side code.
{% endhint %}

***

### 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 ](https://share.hsforms.com/1ubpg6RBoQgKOISkRMEViwg5auur)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`          |

{% hint style="info" %}
Use this endpoint to verify your integration before making any other CSVBox API calls.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.csvbox.io/advanced-installation/auth-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.