Skip to content

How to Authenticate

This guide explains how to authenticate your requests to the CarvOS API.

API Key Authentication

All API requests require an API key passed in the X-API-Key header:

curl -X POST "https://api.carvos.io/v1/candidates" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: your-client-id" \
  -H "X-ATS-User-ID: your-user-id" \
  -H "Content-Type: application/json" \
  -d '{"candidate_id": "test-123", "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com"}'

Context Headers

Operations that act on behalf of a client and user require additional context headers:

Header Required Description
X-API-Key Always Your ATS API key
X-ATS-Client-ID For entity operations ATS client identifier (maps to workspace)
X-ATS-User-ID For entity operations ATS user identifier (maps to member)

Error Responses

Authentication failures return a 401 Unauthorized response:

{
  "detail": "Invalid or missing API key"
}

Missing required headers return a 422 Unprocessable Entity response.

Security Best Practices

Warning

Keep your API key secure

  • Never expose your API key in client-side code
  • Rotate keys periodically
  • Use environment variables, not hardcoded values

Next Steps