Personal API keys
Make your own GreenHired API key as a job seeker or employer: where to click, what you can allow, how long it lasts, the limits, and how to remove it.
#Make a key
A personal key lets your own scripts and systems call the account API as you. You make it yourself, in about a minute, on the Connected apps page of your account. It is shown once, so copy it straight away.
| Item | Job seekers | Employers |
|---|---|---|
| Where | Profile and settings, then Account, then Connected apps: /seeker/profile?tab=connected-apps | Company, then Connected app: /recruit/company/connected-app |
| Who may | Every job seeker | The company roles the company owner allows. By default owners and HR managers |
- Sign in. If your sign-in is older than 30 minutes, the page asks you to sign in again first.
- Give the key a name that says what it is for, such as "my job tracker".
- Tick the permissions it needs. Write permissions are never ticked for you.
- Choose how long it lasts: 1 to 365 days, 90 by default.
- Press Make key and copy it. GreenHired keeps only a fingerprint, so it cannot be shown again.
We also email you a notice that a key was made. The email never contains the key.
#Permissions
| Permission | For | Allows |
|---|---|---|
profile:read | Job seekers | Your name, headline, summary, location, skills, desired roles, job search status and work mode. Not your email, phone number, CV or password |
profile:write | Job seekers | Change your headline, summary, skills, desired roles, job search status and work mode |
applications:read | Job seekers | The jobs you applied to and where each stands. Not your CV, cover letter, answers, messages or notes |
saved:read | Job seekers | Your saved jobs |
saved:write | Job seekers | Save an open job, remove a saved job (up to 500 saved) |
company:read | Employers | Your company's public profile and your role in it |
jobs:read | Employers | Your company's jobs, one job in full, and how many applications each has. Not applicants |
jobs:write | Employers | Create, change, publish, close and remove your company's jobs. Needs jobs:read, and the company owner must switch it on. Personal keys only |
A write permission brings its read permission with it. There is no permission for applicants, messages, other companies, passwords or billing.
#Limits and lifetime
| Limit | Default |
|---|---|
| Live keys per person | 5 |
| Lifetime | 90 days, up to 365 |
| Requests per key per minute | 60, and 30 changes a minute |
| Requests per key per day | 1,000 for a job seeker's key, 5,000 for an employer's key. Resets at 00:00 UTC |
| New jobs per company per day | 20, for all of a company's keys together |
See Rate limits for the headers and error codes.
#When a key stops
- You remove it on the Connected apps page.
- It reaches its end date.
- Your password changes or is reset, you turn off two-factor sign-in, you sign out everywhere, or GreenHired support signs you out. Every personal key stops at once.
- The account is suspended or deleted.
- For employers: a company owner or a GreenHired admin removes it, your company role is no longer allowed to connect, or the company requires two-factor sign-in and you have not turned it on.
- GreenHired switches personal keys off for everyone (a kill switch for emergencies).
A removed or ended key answers 401 invalid_token. Make a new one.
#Frequently asked questions
- Why can I not tick jobs:write?
- Only employers can, and only when a company owner has switched on job changes for the company. Ask an owner to turn it on under Company, then Connected app.
- Can I see my key again later?
- No. Only the first few characters are shown in the list, so you can tell your keys apart. Make a new key if you lose one.
- Does a personal key work on the public jobs API?
- No. Personal keys (
ghpk_) are for the account API. The public jobs API uses a different key (ghk_). See Authentication. - What happens to my keys if I change my password?
- They all stop. That is deliberate: a password change is the moment to be sure nothing old still has access. Make new keys afterwards.
Was this page helpful?