Authorization Code Flow (3-legged OAuth)

Use this OAuth flow in applications that act on behalf of another user. Indeed displays an OAuth consent screen for users to login and give applications specific permissions.

---

By using this API, this API documentation, and/or building the integration, you agree to the Additional API Terms and Guidelines.

---

In this OAuth flow, an application can act on behalf of another user. To do this, Indeed displays an OAuth consent screen.
The user must login and give your application specific permissions. Use this flow if you want your app to:

• Act on behalf of other Indeed user accounts and the employers associated with them
• Display an OAuth consent screen

To call an Indeed API, you need the following:

• A client ID and secret
• An authorization code or refresh token
• An access token

OAuth Overview

Steps to authenticate to an Indeed API

See the instructions for each of the following steps:

Get a Client ID and Secret

Your client ID and secret identify your application. These are also called API keys or API credentials. You only need to get these once per app. If you are creating a test version and a production version of your app, you will need to generate two sets of API credentials.

One-time Steps

1. Navigate to the Indeed Application Registration page.

2. Log into your Indeed account.

3. Click the Register new application button.

4. Enter your Application Name. For example, AceRecruitersApp.

   • Note: If you are creating a test and production version of your app, add -dev to the name of the test version and -prod to the production version. For example, AceRecruitersApp-dev and AceRecruitersApp-prod.

5. Select OAuth 2.0.

6. Select Authorization Code because your app will act on behalf of other Indeed users, and you would like Indeed to display a consent screen in the authorization flow.

7. Because you selected Authorization Code, you must add at least one redirect URL. A redirect URL is a page on your website where Indeed redirects a user after attempting to authorize your app on behalf of 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.

8. Click the Register button.

9. The page displays the Client ID and Client Secret generated for your application.

Example

Application Name: Ace Recruiters LLC
Client ID:        6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b
Client Secret:    02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv

Important: Store your client ID and Secret securely. For example, never store your client ID and Secret in a public git repository. Also, do not share them except when you pass them to Indeed in API calls.

Get an Access Token

You must pass your access token in every API call. This is different from a client ID and secret. Your access token tells us which Indeed account to look up and that your application is authorized to make API calls on behalf of this Indeed account. Indeed's access tokens use the OAuth 2.0 protocol. Specifically, they follow the IETF OAuth 2.0 Authorization Framework - RFC6749.

Prerequisite: Make sure you already have a client ID and secret before you proceed.

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 their behalf. To do this, add an Indeed authorization link to your application using the following URL and parameters:

URL Path

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

Parameters

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&state=employer1234&scope=email+offline_access+employer_access

Optional: 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

If the user clicks the Allow button, then we redirect the user back to your application, to the page at the redirect_uri with the following parameters appended:

Your redirect_uri page must capture the code parameter.

Example Redirect URI

GET http://www.acerecruitersllc.com/oauth/indeed?code=rXZSMNyYQHQ&state=employer1234

Request Your User's Access Token

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

URL Path

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

Note: Be sure to use the POST HTTP method.

Headers

A couple of HTTP headers are required:

Fields

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://localhost:3000/oauth/callback' \
 -d 'grant_type=authorization_code' \
 https://apis.indeed.com/oauth/v2/tokens

Receive the Access Token

The JSON response contains the following tokens and fields:

Example Response

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

Store the access token and refresh token securely.

Error Example

For more information about error types, see IETF OAuth 2.0 Authorization Framework - RFC6749.

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

Call an Indeed API

Prefix the string Bearer to your access token value, and pass the concatenated string in an Authorization header with each API call.

For an example of how to make an API call, see the User Info endpoint example below.

Refresh Your Token

When requesting an access token, if you included the offline_access scope, you receive a refresh token with your access token. Access tokens are valid for one hour (3600 seconds). Use this refresh token to refresh an expired 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.

URL Path

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

Note: Be sure to use the POST HTTP method.

Headers

A couple of headers are required:

Fields

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":"eyJhbGciOiJIUzI1NiIslKxwRJSMeKKeJf36POk6yJV_adQs[...]",
   "id_token":"eyJraWQiOiJlMzEzZTc4My1lM2YwLTQ3ZWMtYmJlMi1jMWRlNGYy[...]",
   "refresh_token":"rXZSMNyYQHQ",
   "convid":"1c1a1s8540kkt89p",
   "scope":"email offline_access",
   "token_type":"Bearer",
   "expires_in":3600
}

Error Example

For more information about error types, see IETF OAuth 2.0 Authorization Framework - RFC6749.

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

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

Pass your valid access token in each API request.

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.

Get User Info

When using 3-Legged OAuth (the Authorization Code flow), there are two ways to retrieve information about the user that registered the app.

• ID Token
• UserInfo endpoint

---

Using an ID Token

The OpenID Connect specification describes an ID token. We always return an ID token with the access token. The ID token contains information about the current user and includes:

Name	Type	Description	Example
sub	string	A unique identifier of the user's account.	248289761001
email	string	The user's email address.	mina.ray@myemail.world
email_verified	boolean	Whether the user has verified their email address.	true
employers	object	The list of employer accounts (IDs and names) associated with the user account. This field requires that the user grant the employer_access scope.

To include the email and email_verified fields in the ID token, an app must request and receive the email scope.

When you use 3-Legged OAuth (the Authorization Code flow) to request an access token, you also get an ID token automatically. Whereas an Access Token is designed to be read by a resource server (an Indeed API), an ID Token is designed to be read by a third-party app.

Example Request

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' \
  -d 'code=qCwk_cdC4Ms' \
  -d 'client_id=a0c3b1092225d3e99f85d7aa3fe1e6001f9a0bb798717cbc2008e58fbda3ef16' \
  -d 'client_secret=1YFoyZOWmr83njlsIuyCL9QQq5jZkRCR4UtmHGp22MRzjIhe5RbynnAGmuYLFbYx' \
  -d 'redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Foauth%2Fcallback' \
  -d 'grant_type=authorization_code' \
  https://apis.indeed.com/oauth/v2/tokens

Example Response

{
  "access_token":"eyJraWQiOiINiYzIwMDh9hrYboL9BMnU_Pfbv41Nqj3nUuMbprUtRgQ",
  "convid":"1erq23om7t5bu800",
  "scope":"email employer_access",
  "id_token":"eyJraWQiMWQ4NTciLCJ0eXAiOiJKV1LmNvbSzNjMwfQ.Jrb1fX-aPtkV9nQK9U1LFP0V61eEApo3pFFPaGjT9zA",
  "token_type":"Bearer",
  "expires_in":3600
}

You can decode the ID token above by pasting it into the form at https://jwt.io.

Example

{
  "aud": "a0c3b1092225d3e99f85d7aa3fe1e6001f9a0bb798717cbc2008e58fbda3ef16",
  "sub": "d2d1962c0664d970",
  "employers": [
    {
      "id": "13ef9940a7c1f0500a7e411e74178c4e",
      "name": "Dharma Initiative"
    },
    {
      "id": "6d2f02224e30d401810b1726eb246d8d",
      "name": "Umbrella Corporation"
    }
  ],
  "email_verified": true,
  "iss": "https://secure.indeed.com",
  "exp": 1610417960,
  "iat": 1610414360,
  "email": "swalther@indeed.com"
}

You get the result above only when the user has granted your app both the email and employer_access scopes. If a user does not grant these scopes then you only receive the sub field.

The ID Token is a base-64 encoded JSON Web Token (JWT). Because the JSON Web Token is signed, you can verify that the token has not been tampered with by using the public key located here:

https://secure.indeed.com/.well-known/keys

If you paste the key into the form at https://jwt.io then you can verify that the ID Token is valid.

UserInfo Endpoint

You must have an OAuth access token before you can call the UserInfo endpoint. Furthermore, to call the UserInfo endpoint, you must retrieve the access token by using the authorization code grant type.

The following CURL command illustrates calling the UserInfo endpoint (access token shortened for readability):

curl -H 'Authorization:Bearer eyJraWQiOiI1OTdjYTgxNC03YTA2LTR0zh0Elm9A' https://secure.indeed.com/v2/api/userinfo

You get different information from the UserInfo endpoint depending on the scopes that a user has granted to your OAuth app. If the user has not granted your app any scopes, then you simply receive the sub field which represents a user's account ID:

{"sub":"d2d1962c0664d970"}

If the user has granted your app the email scope, you receive the email and email_verified fields:

{
  "sub": "a95064930d19bbc7",
  "email": "swalther+samples@indeed.com",
  "email_verified": true
}

Finally, if the user has granted your app the employer_access scope, you receive a list of employers (advertisers) associated with the user account.

{
   "sub": "bc8c847009a955c9",
   "email": "swalther+employer@indeed.com",
   "email_verified": true,
   "employers": [
      {
         "id": "084a39249af95beedfb90cc5d2b8833c",
         "name": "Dharma Initiative"
      },
      {
         "id": "865e08b649774436ee1f410b611fad7c",
         "name": "Umbrella Corporation"
      },
      {
         "id": "4bc393648e880bc94dd6cef8efbc8486",
         "name": "US Robotics and Mechanical Men"
      }
   ]
}

You can call the user information endpoint to request account information for the current user. This endpoint returns exactly the same information as the ID token. Like the ID token, you must request, and receive, the email scope to get the email and email_verified fields.

One use case for this resource is creating Log in with Indeed buttons.

URL Path

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

Headers

Send the access token in an Authorization header.

Header	Value
Authorization	Bearer <access_token>

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.

Name	Type	Description	Example
sub	string	A unique identifier of the user's account.	248289761001
email	string	The user's email address.	mina.ray@myemail.world
email_verified	boolean	Whether the user has verified their email address.	true

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
}

Use Authorization Headers

Optionally, instead of passing your client_id and client_secret in the request body to the /oauth/v2/tokens endpoint, you can encode these credentials and pass them in an Authorization header.

Note: You can only pass an authorization header when you request an access token or refresh your token via the /oauth/v2/tokens endpoint.

To generate this authorization header, concatenate the client_id and client_secret together with a colon as a separator, and then apply the base64 encoding algorithm on the resulting string.

base64.encode("<client_id>:<client_secret>");

Example

base64.encode("5e175cbb7f88e2048bd95323bbc9ca2fcec32ad60f95f7ee66ab53e099abe6f3:pJ4qRe2sdXRP0Whr3bwz9D37exFuuOtqJDRHMmmlLWV7J25rH7oItrPNCKzhaQf2");

Pass the Base64 encoded string as a basic Authorization HTTP header.

Example

Authorization: Basic NWUxNzVjYmI3Zjg4ZTIwNDhiZDk1MzIzYmJjOWNhMmZjZWMzMmFkNjBmOTVmN2VlNjZhYjUzZTA5OWFiZTZmMzpwSjRxUmUyc2RYUlAwV2hyM2J3ejlEMzdleEZ1dU90cUpEUkhNbW1sTFdWN0oyNXJIN29JdHJQTkNLemhhUWYy

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.

Name	Consent String	Description
email	View your email address.	When calling the UserInfo endpoint, this scope returns the email and email_verified fields in the ID token. With this scope, an app can read a user's email and email_verified status from an ID Token or the UserInfo endpoint.
employer_access	List the employers associated with a user account and get an access token for a particular employer.	This scope returns all of the employers associated with your account. With this scope, an app can retrieve the list of employer accounts associated with the user. This scope is also required to get an access token for a particular employer. To retrieve a list of employers and get an access token for a particular employer, see Represent an Employer.
offline_access	Maintain the permissions that you have given.	This scope is required to generate a refresh token. Indeed OAuth access tokens expire after one hour. If you want to retrieve a new access token, and you don't want to pester the user by displaying an OAuth consent screen again, then you can mint a new access token using a refresh token.

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.