API reference · Job seekers and employers

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.

3 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. Make a key
  2. Permissions
  3. Limits and lifetime
  4. When a key stops
  5. Frequently asked questions

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

ItemJob seekersEmployers
WhereProfile and settings, then Account, then Connected apps: /seeker/profile?tab=connected-appsCompany, then Connected app: /recruit/company/connected-app
Who mayEvery job seekerThe company roles the company owner allows. By default owners and HR managers
  1. Sign in. If your sign-in is older than 30 minutes, the page asks you to sign in again first.
  2. Give the key a name that says what it is for, such as "my job tracker".
  3. Tick the permissions it needs. Write permissions are never ticked for you.
  4. Choose how long it lasts: 1 to 365 days, 90 by default.
  5. 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

PermissionForAllows
profile:readJob seekersYour name, headline, summary, location, skills, desired roles, job search status and work mode. Not your email, phone number, CV or password
profile:writeJob seekersChange your headline, summary, skills, desired roles, job search status and work mode
applications:readJob seekersThe jobs you applied to and where each stands. Not your CV, cover letter, answers, messages or notes
saved:readJob seekersYour saved jobs
saved:writeJob seekersSave an open job, remove a saved job (up to 500 saved)
company:readEmployersYour company's public profile and your role in it
jobs:readEmployersYour company's jobs, one job in full, and how many applications each has. Not applicants
jobs:writeEmployersCreate, 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

LimitDefault
Live keys per person5
Lifetime90 days, up to 365
Requests per key per minute60, and 30 changes a minute
Requests per key per day1,000 for a job seeker's key, 5,000 for an employer's key. Resets at 00:00 UTC
New jobs per company per day20, 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.