> ## Documentation Index
> Fetch the complete documentation index at: https://help.csvbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth API

> Authenticate CSVbox API requests with a header-based scheme that validates both your API Key and Secret API Key.

CSVbox requires two authentication headers, `x-csvbox-api-key` and `x-csvbox-secret-api-key`, 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.
</Warning>

## Finding your keys

<Steps>
  <Step title="Log in to the dashboard">
    Log in to the [CSVbox Dashboard](https://app.csvbox.io/).
  </Step>

  <Step title="Open the API Keys tab">
    Click your profile name → **Profile** → **API Keys** tab.
  </Step>

  <Step title="Copy your keys">
    Copy your API and Secret keys.
  </Step>

  <Step title="Regenerate keys if needed">
    If keys are missing or compromised, click **Regenerate Key**.
  </Step>
</Steps>

## Authentication flow

1. The client sends a request to a protected endpoint with both headers.
2. CSVbox validates that:
   * The API key exists and is active.
   * The Secret key matches the same account.
3. If valid, CSVbox returns `200 OK` and the requested data.
4. If invalid, CSVbox returns an appropriate error code.

## Verify credentials API

Verify your credentials with this endpoint.

```text theme={null}
POST https://api.csvbox.io/1.1/auth
```

### 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**

```json 200 OK theme={null}
{
  "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"}` |

### Example requests

<CodeGroup>
  ```javascript cURL theme={null}
  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>"
  ```

  ```javascript jQuery (for testing) theme={null}
  $.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 PHP theme={null}
  <?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;
  }
  ```

  ```javascript NodeJS theme={null}
  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();
  ```
</CodeGroup>

<Danger>
  Never expose your secret keys in browser-side code.
</Danger>

## Security best practices

* Use **HTTPS (TLS)** exclusively.
* Send keys in **headers**, never in URLs.
* Mask secret fields in your UI (`type="password"`).
* Don't log raw keys. Mask them (for example, `****abcd`).
* Rotate and revoke keys regularly from the dashboard.
* Store credentials as environment variables:
  ```bash theme={null}
  CSVBOX_API_KEY=your_api_key
  CSVBOX_SECRET_API_KEY=your_secret_key
  ```
* For browser apps, always proxy API requests through your backend.

## FAQ

<AccordionGroup>
  <Accordion title="Can I send only the API key?">
    No. Both headers are required for authentication.
  </Accordion>

  <Accordion title="Can I use query parameters for keys?">
    No. Query-based authentication is disabled for security reasons.
  </Accordion>

  <Accordion title="Where should I store my keys?">
    Store them server-side in environment variables or a secrets manager.
  </Accordion>

  <Accordion title="I lost my secret key. What now?">
    Regenerate it from the **API Keys** page.
  </Accordion>
</AccordionGroup>

## Troubleshooting & support

If authentication fails:

1. Verify the exact header names (`x-csvbox-api-key`, `x-csvbox-secret-api-key`).
2. Make sure your account and keys are active.
3. Confirm you're using **HTTPS**.
4. If it still fails, 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` |

<Note>
  Use this endpoint to verify your integration before making any other CSVbox API calls.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.