Upgrade OAuth

To upgrade your integration from v1 to the v2 version of the Indeed OAuth endpoint, see the upgrade instructions for each step:

Update Your Application Registration

• Go to the Indeed Application Registration page, and review your application's information.
• Make sure you add at least one redirect URL. A redirect URL is a page on your website where Indeed redirects a user after attempting to authorize the user. If authorization is successful, then we pass an authorization code to your redirect URL. If you would like to test your OAuth application on your local machine, you can set one of your redirect URLs to http://localhost.

Get an access token

Indeed's access tokens use the OAuth 2.0 protocol. Specifically, they follow the IETF OAuth 2.0 Authorization Framework.

Follow these steps to get an access token on behalf of an Indeed user. Repeat these steps for each user:

a.  Request an Authorization Code
b.  Receive the Authorization Code
c.  Request Your User's Access Token
d.  Receive the Access Token

Request an Authorization Code

The owner of an Indeed account must authorize your application to call the API on its behalf.

The URL path for the authorization link, which you send to the user, has changed from https://secure.indeed.com/account/oauth to:

https://secure.indeed.com/oauth/v2/authorize

Parameters

The parameters have not changed, but the redirect_uri parameter is now required.

The redirect_uri is the page on your site that captures the authorization code. It must match one of the redirect URLs registered with your application. You can use http://localhost as one of your redirect URLs.

Example Request

https://secure.indeed.com/oauth/v2/authorize?client_id=6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b&redirect_uri=http%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed&response_type=code&scope=email+offline_access&state=employer1234

If you prefer to use a button instead of a link, then you can create a Log In with Indeed button.

Receive the Authorization Code

This step has not changed.

• The user clicks on the authorization link and logs in to Indeed's site.
• The OAuth consent page asks the user to give your application access.
• We redirect the user to your redirect_uri with the following parameters appended:

Request Your User's Access Token

Next, send the authorization code back to Indeed to get an access token.

The URL path has changed from https://secure.indeed.com/oauth/tokens to:

POST https://apis.indeed.com/oauth/v2/tokens

Headers

The required headers have not changed.

Fields

The fields have not changed, but the redirect_uri must match the one you used to request an authorization code.

Example Request

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' \
 -d 'code=rXZSMNyYQHQ' \
 -d 'client_id=6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b' \
 -d 'client_secret=02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv' \
 -d 'redirect_uri=http://www.acerecruitersllc.com/oauth/indeed' \
 -d 'grant_type=authorization_code' \
 https://apis.indeed.com/oauth/v2/tokens

Receive the Access Token

The JSON response contains the access_token, id_token, expires_in, token_type, and refresh_token.

The id_token field is new. This field is a JSON Web Token that contains the same information that you can retrieve from the User Info endpoint: sub, email, email_verified. The id token includes the email and email_verified fields only if your application requests (and is granted) the email scope.

The format of the scope field has changed. In v1, this field returns the array ["all"]. In v2, this field returns a string of scopes separated by spaces. See scopes.

Finally, in v2, we return a refresh token only when your application requests (and is granted) the offline_access scope. In this case, we also include the field "consented_scope", which represents all scopes that a user has granted the application.

Example Response

{
  "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ[...]",
  "id_token":"eyJraWQiOiJlMzEzZTc4My1lM2YwLTQ3ZWMtY[...]",
  "refresh_token":"rXZSMNyYQHQ",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope": "email offline_access",
  "consented_scope":"email offline_access"
}

Error Example

{
  error: "invalid_request",
  error_description: "Invalid authentication request."
}

Pass Your Token to the API

This step has not changed.

Refresh Your Token

Access tokens are valid for one hour (3600 seconds). To refresh an expired access token, use the refresh token returned with your user's access token. The refresh token is valid for 60 days from when it was issued. With each refresh, the refresh token's expiration date is extended to 60 days from the most recent refresh.

We return a refresh token with the access token only when your application requests (and is granted) the offline_access scope.

The URL path path has changed from https://secure.indeed.com/oauth/tokens to:

POST https://apis.indeed.com/oauth/v2/tokens

Headers

The required headers have not changed.

Fields

The scope response field has changed. In v1, this field returns the array ["all"]. In v2, this field returns a string representing all of the scopes that have been granted by the user. For example, if your application requests the email and offline_access scopes and the user grants these scopes during the authorization step, then the scope response field has the value email offline_access as a string.

Example Request

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' \
  -d 'refresh_token=8qE_nKXUng4' \
  -d 'client_id=6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b' \
  -d 'client_secret=02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv' \
  -d 'grant_type=refresh_token' \
  https://apis.indeed.com/oauth/v2/tokens

Example Response

{
  "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "refresh_token":"rXZSMNyYQHQ",
  "convid":"1c1a1s8540kkt89p",
  "scope":"email offline_access",
  "token_type":"Bearer",
  "expires_in":3600
}

Note: The new access token is also valid for one hour only. You must refresh this token after that.

User Info

The user information endpoint that is used to request account information has changed. This endpoint returns the user id, email address, and email verification status associated with the access token. The response only includes the email and email_verified fields if you request the email scope, and the user grants it to you.

The host name remains the same, secure.indeed.com. However, the endpoint path has changed. It is no longer /v1/api/account and has changed to /v2/api/userinfo.

Also, you can no longer pass the access token as a URL parameter. You must pass the access token in an authorization header.

URL Path

GET/POST https://secure.indeed.com/v2/api/userinfo

Headers

Send the access token in an Authorization header.

Fields

This endpoint does not have any request fields. In the request, pass only the access token in an Authorization header, with Bearer pre-pended before the access token string.

A successful request returns the HTTP status code 200 and the following response fields.

Example Request

GET /v2/api/userinfo HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Host: secure.indeed.com

Example Response

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
   "sub": "248289761001",
   "email": "mina.ray@myemail.world",
   "email_verified": true
  }

Scopes

When requesting an access token, you can request one or more scopes. The scopes determine the permissions granted to your app.

Currently, Indeed supports the following authorization scopes:

Note: Some Indeed APIs have additional scopes. You may need to pass these scopes when you request the access token. For API-specific scopes, see the API documentation for each API.

When using the Authorization Code Flow (3-Legged OAuth), the authorizing user can choose which checkboxes to select on the consent screen. The user can decide on the particular scopes that they want to grant your app. They could decide to grant all of the scopes, none of the scopes, or only particular scopes.

Your app can detect the actual scopes that a user granted by reading the scope field of a token response.

Example:

  {
    "access_token":"eyJraWQiOiI1OTdjYTgxNC03YTA2LTRkZTMtO",
    "refresh_token":"ZenoK4KeQsg",
    "id_token":"eyJraWQiOiI1OTdjYTgxNC03YTA2LTE69SSJkjQQ",
    "scope":"offline_access employer_access email",
    "consented_scope":"offline_access employer_access email",
    "convid":"1er835qvtu54n800",
    "token_type":"Bearer",
    "expires_in":3600
  }

Using Incremental Authorization

We encourage apps to only request the scopes that they actually need at the time that they actually need them. Therefore, we recommend that apps request scopes incrementally.

Indeed OAuth supports incremental authorization. If a user has already granted your app a scope in the past, then the user does not need to grant the same scope again. Requesting offline_access scope is required for incremental authorization to work. For example, if your app requests the email scope to view the user's email addresses, also request the offline_access scope.

Suppose the user attempts to access additional functionality that your app provides, and this additional functionality requires the employer_access scope. When the OAuth consent screen displays a second time, the app does not need to request the email and offline_access scopes again. The OAuth consent screen prompts the user to grant only the new scope: employer_access.

On the consent screen, the user can view scopes they previously granted under the Current permissions tab. If the user clicks that tab, then the user can see that they have already granted the email and offline_access scopes.

Revoking OAuth Scopes

When using the Authorization Code Flow (3-Legged OAuth), a user can revoke the scopes granted to a particular app via the authorized applications page.

Note: You currently cannot revoke scopes individually. You can revoke all scopes and, when using the app, grant scopes again.

Represent an Employer

A single Indeed user account can be associated with one or more employer accounts. An Indeed API might require you to represent a particular employer when calling the API. There are two ways that you can associate an employer with an access token: you can use the Indeed Employer Selection Screen or you can create a Custom Employer Selection Screen.

Display the Indeed Employer Selection Screen

You can use the prompt=select_employer parameter when creating an authorization link to trigger the display of the Indeed Employer Selection Screen. When using the prompt=select_employer parameter, your OAuth app must also request the employer_access scope or the Indeed Employer Selection Screen will not be displayed. For example, the following link includes both the prompt=select_employer parameter and a request for the employer_access scope:

https://secure.indeed.com/oauth/v2/authorize?client_id=bf7622efee705862320df0f5c7690b22f60ba24f236aaf4adf5b7a36fa0adcf1&redirect_uri=https%3A%2F%2Fexample.com%2Foauth&response_type=code&state=random&scope=email+offline_access+employer_access&prompt=select_employer

This authorization link will trigger the following three screens to be displayed:

1. Authentication Screen — the standard Indeed Authentication Screen is displayed when the user is not already logged into Indeed.
2. OAuth Consent Screen — the OAuth Consent Screen enables a user to grant consent for any scopes requested by the OAuth app (such as the employer_access scope).
3. Indeed Employer Selection Screen — the Indeed Employer Selection Screen enables a user to select a particular employer from a list of all of the employers associated with the user.

The Indeed Employer Selection Screen in the above figure displays a list of two employers associated with the user account: US Robotics and Mechanical Men and Umbrella Corporation. If the user selects one of the employers, and submits the page, then the employer id is transmitted to your OAuth app as a parameter of the Redirect URI:

https://example.com/oauth/callback?state=random&employer=6d2f02224e30d401810b1726eb246d8d&code=e_IEr5UlBys

Notice that the URL above includes an employer parameter that represents an employer id. You can use the employer id when requesting an access token to associate the access token with a particular employer like this:

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' \
 -d 'code=e_IEr5UlBys' \
 -d 'client_id=bf7622efee705862320df0f5c7690b22f60ba24f236aaf4adf5b7a36fa0adcf1' \
 -d 'client_secret=02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv' \
 -d 'redirect_uri=https://example.com/oauth' \
 -d 'grant_type=authorization_code' \
 -d 'employer=6d2f02224e30d401810b1726eb246d8d' \
 https://apis.indeed.com/oauth/v2/tokens

You can also use the employer parameter when using a refresh token to request a new access token.

If there are no employers associated with a user account, or the user does not select an employer, then an employer parameter is not passed with the redirect URI back to your OAuth app.

Display a Custom Employer Selection Screen

Indeed recommends that you use the standard Indeed Employer Selection Screen to enable users to select a particular employer. If you want to customize the appearance of the Employer Selection Screen then you also have the option of retrieving the list of employers and building an employer selection screen yourself. Follow these steps:

Step 1: Retrieve an Access Token, ID Token, and Refresh Token

Follow the get an access token steps to trigger the OAuth consent screen and get an access token with the employer_access and offline_access scopes.

The query returns an access token, ID token, and refresh token. You can get a list of employers associated with the current user by decoding the ID Token (see Get User Info).

Step 2: Create a Custom Employer Selection Screen

Now that you have a list of employers, you can build a user interface that enables the user to select a particular employer.

Step 3: Retrieve an Access Token that Represents a Particular Employer

Use the selected employer's ID to retrieve a new access token that represents that employer. To do this, pass the employer ID in the employer parameter of the /tokens endpoint.

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' \
  -d 'refresh_token=4U0xku8M9u0' \
  -d 'client_id=b0c3b1092225d3e99f85d7aa3fe1e6001f9a0bb798717cbc2008e58fbda3ef16' \
  -d 'client_secret=2YFoyZOWmr83njlsIuyCL9QQq5jZkRCR4UtmHGp22MRzjIhe5RbynnAGmuYLFbYx' \
  -d 'grant_type=refresh_token' \
  -d 'employer=13ef9940a7c1f0500a7e411e74178c4e' \
  https://apis.indeed.com/oauth/v2/tokens

Note that the grant_type parameter has the value refresh_token. The refresh_token parameter has the refresh token retrieved in step one. Because you retrieved the new access token using a refresh token, an OAuth consent screen is not needed. The request also includes an employer parameter with the Dharma Initiative employer ID as its value.

Use this access token for API calls on behalf of the consenting user and only for that particular employer.