Authentication & Idempotency

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

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

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

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

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

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

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