Generating and using API credentials

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.

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

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.

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

• 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.
  
  • Use the preset selection options at the top of the endpoint list to bulk-select endpoints.
  • Hover over the question mark next to each endpoint to reveal the specific call that will be made by the API using that endpoint.
  • 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.

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

• Input a key name 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).
• Click the Generate key button to generate the unique API key.
• 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 (*).
• Click the Copy Key button next to the API key (which can be found next to the 'Key name' field).

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

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.