# Authentication & API Keys

Hunty's API supports two authentication mechanisms. All requests must include at least one.

## Bearer Token (JWT)

Used for requests made on behalf of an authenticated user session.

Include the token in the `Authorization` header:

```http
Authorization: Bearer <your_jwt_token>
```

## API Key (`x-auth-api-key`)

Used for server-to-server integrations. The API key is tied to a specific company and grants access to the endpoints explicitly approved during the request process.

Include the key in the `x-auth-api-key` header:

```http
x-auth-api-key: <your_api_key>
```

## Rate Limits

API keys are subject to a rate limit of **25 requests per minute**. Exceeding this limit returns an HTTP `429 Too Many Requests` response. See the [Rate Limits](/docs/rate-limits) page for guidance on handling this.

## Requesting an API Key

To request an API Key for your company, send an email with the following details:

**To:** comite-seguridad@hunty.com
**CC:** santiago@hunty.com, enzo.garcia@hunty.com
**Subject:** `Solicitud API Key - <companyId>`

**Body must include:**

1. **Company and responsible contacts** — company name, plus the full name, role, and email for **two contacts**:
  - **Primary responsible** — the person responsible for the integration.
  - **Secondary (backup) responsible** — a second contact, ideally their manager or a shared team mailbox. This ensures deprecation and End of Life notices still reach someone if the primary contact leaves the company or changes roles.
2. **List of endpoints** — for each endpoint your integration needs access to, include:
  - The endpoint path and HTTP method (e.g., `GET /v2/vacancies/company/{companyId}`)
  - A brief justification of the use case
3. **EOL acknowledgment** — a statement confirming that the responsible contact has read and understood the [End of Life Policy](/docs/eol), including the deprecation process and the 2-month support window.


**Example email body:**

```
Hi,

We would like to request an API Key for the following company:

Company: Acme Corp
Primary responsible: Jane Doe, Integration Lead — jane.doe@acmecorp.com
Secondary responsible: John Smith, Engineering Manager — it-team@acmecorp.com

Endpoints requested:

1. GET /v2/vacancies/company/{companyId}
   Use case: Retrieve the list of active vacancies for our company to sync with our internal ATS.

2. POST /v2/vacancies/{vacancyId}/applications
   Use case: Submit candidate applications directly from our recruitment platform.

EOL acknowledgment: I confirm that I have read and understood the Hunty API End of Life Policy, including the deprecation process and the 2-month support window for deprecated features.

Thank you.
```