API reference · Start here

Authentication and keys

How to authenticate with the GreenHired API: the two kinds of key, where to send them, how to get an API key or make your own, and how to keep a key safe.

3 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. Two kinds of key
  2. Send the key
  3. Get an API key for the public jobs API
  4. Make a personal key
  5. Keep a key safe
  6. Frequently asked questions

#Two kinds of key

You send a key in every request. Which key depends on the API:

ItemAPI key (ghk_)Personal key (ghpk_)
Works withThe public jobs API at api.greenhired.com, and the MCP server in key modeThe account API at api.greenhired.com/v1/assistant
Belongs toAn app or a partner, with a name, permissions and limitsOne person: a job seeker or an employer
How you get itAsk the GreenHired team. A GreenHired admin makes itMake it yourself on your account page
Permissionsjobs:read, categories:read, insights:read, companies:read (reserved)Chosen by you when you make the key, within what your account may give
ShownOnce, when it is madeOnce, when you make it
LifetimeUntil it is revoked90 days by default, 365 at most

#Send the key

Put it in the Authorization header as a bearer token. The public API also accepts the X-API-Key header. Never put a key in the address: addresses end up in logs.

curl -s https://api.greenhired.com/v1/ping -H "Authorization: Bearer ghk_YourKeyHere"
# the same with the other header (public API only):
curl -s https://api.greenhired.com/v1/ping -H "X-API-Key: ghk_YourKeyHere"

#Get an API key for the public jobs API

API keys are issued on request while the API is new. Write to partners@greenhired.com with what you are building, which pages or tools will show GreenHired jobs, and the permissions you need. A GreenHired admin makes the key and sends it to you once.

A key has a name, a list of permissions and two limits. If a request needs a permission the key does not have, the answer is 403 insufficient_scope.

PermissionOpens
jobs:readGET /v1/jobs, GET /v1/jobs/{slug} and the MCP tools search_jobs and get_job
categories:readGET /v1/categories and the MCP tool list_categories
insights:readGET /v1/insights/salaries
companies:readReserved. There is no company endpoint yet, so it opens nothing today

GET /v1/ping needs any valid key and no particular permission. GET /v1/openapi.json needs no key.

#Make a personal key

Job seekers and employers make their own key. Sign in, open the Connected apps page of your account and choose the permissions. The steps, limits and rules are on Personal keys.

#Keep a key safe

  • Store it in an environment variable or a secret manager. Do not commit it, paste it into a chat, or send it in a ticket.
  • Use it from a server you control. Do not put it in a web page, a mobile app or a browser extension.
  • Use one key per app, so you can remove one without breaking the rest.
  • If a key leaks, remove it. Personal keys: remove it on your Connected apps page. API keys: tell the GreenHired team and ask for a new one.
  • Give a key only the permissions it needs. A read-only job tracker does not need a write permission.

#Frequently asked questions

Why is a key shown only once?
We keep only a SHA-256 fingerprint of it, so nobody at GreenHired can read it back. That also means a database leak does not leak working keys.
Can one key work for both APIs?
No. An API key (ghk_) is for the public jobs API. A personal key (ghpk_) is for the account API. They are made in different places and carry different permissions.
What does insufficient_scope mean?
The key is valid but does not carry the permission that endpoint needs. For an API key, ask the team to add it. For a personal key, make a new key with that permission ticked.
Can I rotate a key without downtime?
Yes. Make the new key, deploy it, check with GET /v1/ping or GET /me, then remove the old one.