OAuth for Partner Product Integrations

OAuth is part of our partner integration program, and apps must be registered. Find more details about building a partner integration on the partner page, and more about registering below.

OAuth offers a great user experience and a high degree of security. As of 2020, all Lever integrations are authenticated using OAuth. Here, we will have a look at all things OAuth for your integration:

1. OAuth, Customers and the Lever Product
2. OAuth at a High Level
3. Getting Set-up with OAuth
4. Implementing
5. And Finally, Debugging

Let's jump ahead and see how OAuth will work with your production integration.

OAuth, Customers and the Lever Product

Once released, Lever Super Admins will authenicate your app on behalf of their whole organization. By clicking the connect to Lever button in your product, they will begin the authenication steps starting with the redirect in Step 1.

Once they've accepted the permission scopes you've requested, your app will be displayed in their Lever settings page using the logo you submit when you register. There, the Super Admin will also be able to revoke access to your app.

At this time, OAuth is not supported for customers in the EU. Please let us know if a significant portion of our mutual customers are in the EU.

OAuth at a High Level

Where API Key authentication requires the customer to transfer the key manually to you, the integrator, OAuth allows the customer to enable your integration in one click. No sensitive data transfer; no manual steps; and much less chance of error.

You will create an app on our Auth server. Your app will be identified by a client ID and a client secret.

Our mutual customers will be users, who will grant your app access to the Lever data you request in your scopes. This grant of access will provide you an authorization code.

You will exchange the authorization code for an access token. The access token will expire, but the customer does not need to re-authenticate your app. You wil simply use the refresh token to exchange for a new access token. Repeat this process, factoring in expiry times for the access token, to maintain persistent authentication.

Getting Set Up with OAuth

To get started with OAuth you will need to register your app/integration. You may want to save a copy of your submission for debugging in the future.


To register you will need:

1. Integration Name
2. Descriptions of your integration
3. Callback URI
4. Square Logo URI
5. Required Scopes

Integrations Name

  • Your company name, or the name of the product being connected to Lever

Description of your app

  • The description must be between 20 and 140 characters.
  • The description will be displayed in the Lever integration ecosystem.

Callback URL(s)

  • The callback URL is where the autorization code will be returned to you once a user grants your app access, in Step 2 of the authentication process.
  • For example: "https://yourcallback?code:e7ySnlkpS61E8vLA&state=vgG5sHr6".
  • You may register with one callback, and request additional through support.
  • During development, on sandbox, callbacks may be 'http'.
  • The link to your logo must be a link, and cannot be to Google Drive, or a link to a download of the image.
  • The images must be square, and the recommended size is 150x150px.
  • The image will be displayed in the Lever product and on the authorization module, both are on a white colored background.

Required Scopes

  • Select the scopes for the required endpoints.
  • Most use cases can be supported with 5 to 8 scopes. There is an absolute maximum of 20 scopes.
  • Write:admin scopes include all Read:admin endpoints. If you select a write scope you are gaining all the read permissions.

Implementing

Get started quickly with our Example App and Postman Collection


While you are building you will use your Lever Integrator Sandbox account to emulate a user authenticating your app. Since you have access to the Sandbox auth server, and a Sandbox account, make sure you are using both the Sandbox API "https://api.sandbox.lever.co/v1" and redirect and request paths, as seen in image below.

Test your OAuth set-up on Postman by following this template. Make sure you choose OAuth 2.0 from the authentication tab. When you have everything entered and you are ready to test in Postman, press the orange "Get New Access Token" button first, and "Send" only after you've successfully authenticated.

OAuth Postman Example

This set-up will not work on Production, as the audience parameter is required in the OAuth flow.

OAuth FAQ

Will the user/customer need to authenticate every API call the integration makes?

No, the user/customer only needs to authenticate once! Persistent authentication is held by using refresh tokens to exchange for new access tokens.

Can callback URLs be different on Sandbox and Production?

Yes! Callback URLs can be unique to sandbox and production. You will have two separate app's, one for each environment, and the configuration can be different.

Can the callback change for each customer that we enable?

No, callbacks are registered with your integration app, and the callbacks used must match those that are registered.

Can we have multiple callbacks, for instance once for staging and one localhost?

Yes, you can register multiple callbacks on your integration app.

Can we use an API Key for development?

The Lever Integrations team is more than happy to help you implement OAuth every step of the way. OAuth is a requirement of the integrations program, and for that reason we do not provide API Keys for development. Let us know if you have any questions or concerns with implementing OAuth.

Debugging

Error Description Solution
Redirect Undefined Redirect window opens message of 'undefined' Ensure all parameters in redirect URL match registration submission. Particularly, the callback/redirect URI matches registration
Redirect Scopes User granting access screen displays only 'offline_access' Correct audience parameter must be added to the redirect URL. The audience parameter should end in a backslash 'https://api.sandbox.lever.co/v1/' or 'https://api.lever.co/v1/' '
401 Unauthorized Error: Unauthorized Check that the secret provided is being used for the ClientSecret, not the Key
403 Forbidden Error: Unable to find a signing key that matches .. Calls may be being made to the incorrect API. While building an integration the sandbox API should be used 'https://api.sandbox.lever.co/v1'
403 Forbidden Error: ClientID not found Incorrect auth URL being used in redirect. While building an integration the sandbox auth URL should be used 'https://sandbox-lever.auth0.com/authorize'
403 Forbidden Error: The key you provided does not have access to this endpoint The user must grant access to a scope in the redirect to grant permission to use the endpoints included. Ensure the scope for the endpoint is listed in the redirect
Scopes must be registered on the Auth server. Register for a new scope to have it included on your app
The write:admin is redundant to the read:admin scopes. If both a write:admin and a read:admin are registered for only the write:admin is included. Try using only the write:admin of a duplicate scope
Include only a single space between each scope. Do not include commas, nor leading or trailing spaces