Authentication

There are two ways to authenticate. Neither takes a company id.

Caller	How	Acts as
MCP clients	Sign in with Hotfix (OAuth)	You, in the company you picked
Scripts on `/v1/employer`	`Authorization: Bearer hf_…`	The person who created the key, as a member

Add https://mcp.hotfix.jobs/hiring to the client with no header. On first use it opens a browser. Sign in, pick a company, and choose an access level:

Read and write can call every MCP tool.
Read only lists and calls only the tools that read data.

The sign-in page says where the app is from by what Hotfix checked, not the name or website the app gives itself: the domain it proved, like claude.ai, or on this computer for an app running locally, such as Claude Code. Allow a local app only if you just started connecting it. Any member of the company can connect. Every tool, reads included, needs a live plan; Free counts as live. Tools run with your permissions, and notes and status changes are attributed to you. Access tokens last 15 minutes and the client refreshes them. Everyone sees the apps they connected under Settings > Connections > AI apps. Owners and admins see everyone’s there, and can disconnect any of them. Disconnect cuts access on the next call. Leaving the company does too. Get started has setup for Cursor, Claude Code, Codex, and VS Code.

Create an API key

In the app, open Settings > Connections, and click Manage on API keys.
Create a key as an owner or admin. A member cannot.
Copy the secret when it appears. Hotfix stores a hash. You will not see the secret again.
Put it in an environment variable. Do not commit it.

Prefix is hf_. Cap is 20 keys per company. A key acts as the person who created it. It stops working when that person leaves the company, so create keys for long-running jobs from an account that will stay. Revoking a key under API keys stops it at once.

curl https://api.hotfix.jobs/v1/employer/applications \
  -H "Authorization: Bearer hf_…"

What a key can call

A key reaches the same hiring data as the MCP tools:

Applications: list, get, search, update one or many at once, notes, activity, record, GET resume, and the resume as text
Custom fields: list fields and set a value
Jobs: list, create, get, update, close preview, and close
Interviews and offers, including attaching an interview already on Google Calendar

Everything else on /v1/employer takes a dashboard session, not a key. That covers mail and drafts, keys, team, billing, webhooks, settings, and connecting your calendar or Zoom. A key does not work on MCP. MCP returns 401 and asks you to sign in instead.

Errors

Status	When
`401`	The key is missing, wrong, or revoked, or the person who created it is no longer a member of the company.
`402`	Your plan has ended. Writes return `plan_ended` until you reactivate it. Reads keep working, so you can still see your candidates and jobs.
`403`	The caller isn’t allowed to do this, like a dashboard session that isn’t a member of the company, or editing a note someone else wrote.
`429`	Too many requests from this key in a short time. Wait a moment and retry.

A 401:

{
  "detail": "A valid API key is required."
}

A 402:

{
  "detail": {
    "code": "plan_ended",
    "message": "Your plan ended. Reactivate it to make changes."
  }
}

Dashboard session

The dashboard sends a session JWT on /v1/employer. You do not mint or send that token. The org on the token is the company.

Get started

Hiring MCP

Jobs MCP

Concepts

API reference

Create an API key

What a key can call

Errors

Dashboard session

​Sign in from an MCP client

​Create an API key

​What a key can call

​Errors

​Dashboard session

Sign in from an MCP client

Create an API key

What a key can call

Errors

Dashboard session