Generating and using API credentials

Follow
Available for User roles Super Admin
Packages All packages

From the Integrations and API page in your Settings, you can generate Application Programming Interface (API) credentials that will allow the tools in your organization's tech suite to access data in your Lever environment. Granting access via API credentials allows you to tailor how information is passed between Lever and other systems in use at your organization. Readers of this article will learn about:

How API credentials work

An API, or Application Programming Interface, is a set of functions and procedures allowing the creation of applications which can in turn access the features or data of an operating system, application, or other service. Simply put, an API is a way for two computer programs to communicate with each other.

An API credential (also referred to as an API key) is a unique string of characters used to authenticate the program that is making a "call" to another program via an API. In this context, think of a "call" as a request to read or modify information made by one program to another. The credential verifies the identity of the program making the call to the program that receives the request. Since API credentials support the security of information passed between programs, they are subject to one-time generation. For this reason, when you generate an API key, you should write it down and store it in a safe location.

API keys can be configured to allow different degrees of access to the program making calls. The degree of access that an API key confers is knowns as its permission.  When generating credentials for the Lever API, the key can be configured to grant two types of permission:

  • Read - allows the program making the call to pull in information from the program that receives the call, consisting of the following actions:
    • Read - for singular items (e.g. an archive reason)
    • List - for sets of items (e.g. a list of users)
    • Download
  • Write - allows the program making the call to modify information in the program that receives the call, consisting of the following actions:
    • Upload
    • Update
    • Delete
    • Remove
    • Reactivate
    • Create
    • Add

The specific informational objects that can be read or written by a calling program are knowns as endpoints. When generating credentials for the Lever API, you can configure which endpoints can be acted upon by the program using that credential.

Types of API credentials in Lever

Within Lever, there are two types of API credentials that you can generate:

Postings API
This API credential is meant to be used to create a custom job site that is connected to your Lever environment. The Postings API credential allows the following actions to take place via your custom job site:

  • Get paginated job postings for your organization
  • Get job postings that match particular queries
  • Get individual job postings (if the posting ID is known)
  • Programatically apply to job postings

All documentation related to this API, as well as example applications, can be found in our Postings API repository.

 

The Postings API also powers Lever's XML job feed. The XML job feed can be used to allow job boards and partners to read your public job postings, all without having to share an API key or manage access. To learn more about this option, refer to our XML job feed help article.

Lever API
This API credential can be used to grant another program access to any data in your Lever environment. Full details on the Lever API can be found in our developer documentation. If you are considering using either Lever API credentials to set up workflows between your Lever environment and other programs in use at your organization, we recommend sharing these resources with your organization's development team so they can scope out the work required to build connections with your existing tech stack.

Generating API credentials in Lever

 

API credentials can only be accessed by users with Super Admin level access.

To generate API credentials, navigate to Settings > Integrations and API > API Credentials.

Generating Postings API credentials

You can find the Postings API credential generated at the top of the page.

API credentials page in Integrations and API settings; close up of Posting API credentials section.

This API key will remain unchanged unless it is manually reset. If you ever reset the Postings API key after you have used it to create a custom job site, you will need to update the key on the backend of your custom job site.

Generating Lever API credentials

To generate Lever API credentials:

  • Click the Generate New Key button

Close of of Lever API credentials section on API credentials page.

  • Input a name for the key that reflects the service or integration that will be using the key
    • This name will appear on any objects in Lever created using that key (via 'write' permission endpoints).
  • If desired, upload a logo image to associate with the key. The image file must be in .png format and be less that 500 KB in size.
    • The image will appear next to certain objects created in Lever using that key (via 'write' permission endpoints). For guidelines on image sizing/formatting, as well as to view an example of how the logo image will appear on created objects, refer to our help article on how to attach an image to an API key.
    • In the list of endpoints, objects next to which the logo image will appear are denoted with an asterisk (*).
  • Under the 'Permissions' heading, select the checkboxes next to the read and/or write endpoints to configure the degree of access that will be conferred by the API key.
    • Hover over the question mark next to each endpoint to reveal the specific call that will be made by the API using that endpoint.
    • Use the preset selection options at the top of the endpoint list to bulk-select endpoints.
    • We advise granting access to the fewest number of endpoints as possible, ideally no more than will be needed by the program making calls, in order to ensure that information security (in the context of 'read' endpoints) and integrity (in the context of 'write' endpoints) is preserved.

Close-up of permissions section in Lever API credential configuration editor with preset selection options outlined.

  • By default, information associated with confidential postings, opportunities, or requisitions will be excluded from the access granted by the Lever API credential. If you wish for the generated API key to grant access to confidential information in your Lever environment, move the 'Allow access to confidential data' toggle to the on position.

Close-up of confidential data access toggle at the botth of the Lever API credential configuration editor.

  • Click the Copy Key button next to the API key (which can be found next to the 'Key name' field).

 

This is the one and only time you will be able to access this key so we advise storing a copy in a safe location.

Arrow pointing to copy key button next to blurred out API key at the top of Lever API credential configuration editor.

  • Click the Done button, followed by the Got It button on the confirmation pop-up

Once you generate the credential it will be listed on the 'API Credentials' page. It is not possible to make changes to the endpoints configured for a credential once it has been generated. In order to make such changes, you will need to delete the current key, generate a new one, and replace the key in the program(s) making calls to your Lever environment. To delete a credential, hover over it in the credentials list and click the trash can icon aligned to its right.

Close-up of Lever API credentials list with on API key listed.

Note that deleting a credential will immediately revoke access for that key, meaning any platforms in which it is used will no longer be able to access the data in your Lever environment.

 

If you are generating a Lever API key for use by a third party or anyone outside of your organization, we recommend sharing the API key by way of a secured service, rather than by email, chat or other plain text methods (e.g. onetimesecret.com, 1ty.me, pwpush.com).

 

If a vendor that you work with has built a valuable integration for you using Lever's API, ask them to consider joining Lever's partner ecosystem. As we continue to invest in our partners and mutual customers, encouraging your vendors to become Lever Partners can start them on the path to getting a more robust and secure integration in place. Vendors interested in joining Lever's partner ecosystem can submit a request via our Partnership Interest Form.
Was this article helpful?
0 out of 0 found this helpful