# 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.

- Source: https://greenhired.com/developers/api/v1/authentication/
- Section: GreenHired developers · API · Start here
- Last updated: 2026-11-21

## Two kinds of key

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

|  | 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*

```bash
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"
```

*JavaScript*

```javascript
const headers = { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY };
const res = await fetch('https://api.greenhired.com/v1/ping', { headers });
```

*Python*

```python
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](mailto: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](https://greenhired.com/developers/api/v1/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.

> **Info:** A `401` is the same answer for a wrong, expired and revoked key (`invalid_key` or `revoked_key` on the public API, `invalid_token` on the account API). If you lose a key, make or request a new one: we cannot show it again.

## 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.

## Related pages

- https://greenhired.com/developers/api/v1/personal-keys/
- https://greenhired.com/developers/api/v1/limits/
- https://greenhired.com/developers/api/v1/errors/
