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 authenticate your app on behalf of their whole organization. By clicking the connect to Lever button in your product, they will begin the authentication 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.

OAuth is supported for customers in the EU. Any integration authorization or action will be re-directed automatically to the appropriate data center.

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 will simply use the refresh token to exchange for a new access token and a new refresh token. Repeat this process, factoring in expiry times for the access token and the refresh 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 authorization 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'.

Link to your Logo

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.

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 the 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