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.
On this page
#Two kinds of key
You send a key in every request. Which key depends on the API:
| Item | API key (ghk_) | Personal key (ghpk_) |
|---|---|---|
| Works with | The public jobs API at api.greenhired.com, and the MCP server in key mode | The account API at api.greenhired.com/v1/assistant |
| Belongs to | An app or a partner, with a name, permissions and limits | One person: a job seeker or an employer |
| How you get it | Ask the GreenHired team. A GreenHired admin makes it | Make it yourself on your account page |
| Permissions | jobs:read, categories:read, insights:read, companies:read (reserved) | Chosen by you when you make the key, within what your account may give |
| Shown | Once, when it is made | Once, when you make it |
| Lifetime | Until it is revoked | 90 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" const headers = { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY };
const res = await fetch('https://api.greenhired.com/v1/ping', { headers }); headers = {"Authorization": "Bearer " + os.environ["GREENHIRED_API_KEY"]}
res = requests.get("https://api.greenhired.com/v1/ping", headers=headers, timeout=15) #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.
| Permission | Opens |
|---|---|
jobs:read | GET /v1/jobs, GET /v1/jobs/{slug} and the MCP tools search_jobs and get_job |
categories:read | GET /v1/categories and the MCP tool list_categories |
insights:read | GET /v1/insights/salaries |
companies:read | Reserved. 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/pingorGET /me, then remove the old one.
Was this page helpful?