Authentication and permissions

Create keys in Nova, under Settings › API. Give each key a name and only the permissions it needs. The secret is shown once, when you create the key. After that Nova only shows the key id, who created it, when, and when it was last used. A revoked key stops working for good.

Send the key

Send the key in the X-Api-Key header of every request:

X-Api-Key: Nova <access_key_id>:<secret>

The examples in this site read the whole header value from an environment variable:

export NOVA_API_KEY="Nova <access_key_id>:<secret>"

Keep the key in your server code and call Nova from there. Never put it in a web page or an app that runs on your users' devices: anyone who can read that code can use the key.

The API does not answer browsers across origins.

Permissions

PermissionAllows
careers-site:applyRead the published jobs and send applications. This is what a careers site needs.
jobs:readRead the jobs of the account with their phases, and list its projects and departments, and search locations.
jobs:writeCreate draft jobs, edit them, and publish, close or reopen them.
candidates:readRead candidates with their files, tags, notes and applications, and the phase history of an application.
candidates:writeCreate and edit candidates, attach files, add notes and tags, add candidates to jobs, and move or reject their applications.
lists:readRead the lists and their people, and the sequences with their candidates.
lists:writeAdd people to a list by LinkedIn URL, which enrols them in the sequences of the list, and remove a person from a list.

The reference page of each call says which permission it needs.

A key acts as the team member who created it. Lists and sequences that are private in Nova are visible to the key only when they are visible to that person; the rest answer 404 as if they did not exist.

What you get when it fails

  • 401 invalid_api_key: the header is missing, malformed, or the key is unknown or revoked.
  • 403 missing_permission: the key lacks the permission the call needs.