> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kota.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server.

# Authentication & Idempotency

> Authenticate and make requests to the Kota API

Every integration with Kota requires server-side API calls to sync employer and employee data. This guide covers authentication and best practices for working with the Kota API.

## Authentication

The Kota API uses API keys to authenticate requests. Test mode secret keys have the prefix `pk_test_` and live mode secret keys have the prefix `pk_live_`.

> **Warning**
>
> Your API keys carry many privileges. Keep them secure and never share them in publicly accessible areas such as GitHub or client-side code.

**Example API call:**

**`cURL`**

```curl cURL
curl https://test.api.kota.io/employees/$employee_id \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>"
```

[Read more about authentication in the API Reference](/api-reference#authentication)

---

## Idempotent Requests

Kota recommends adding an idempotency key to all POST requests. Use a unique key, such as a universally unique identifier (UUID), to safely retry requests if you encounter network errors.

**Example idempotent API call:**

**`cURL`**

```curl cURL
curl https://test.api.kota.io/ENDPOINT \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
  ... rest of request here
```

[Read more about idempotent requests in the API Reference](/api-reference#idempotent-requests)

---