Client Credentials Flow (2-legged OAuth)

Use this OAuth flow in applications that act on behalf of the Indeed user that registered the app and the employer accounts associated with that Indeed user.

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, your application acts only on behalf of the Indeed account that registered your app and obtained the client ID and secret.

Use this flow if you want your app to:

• Act on behalf of the Indeed user that registered the app
• Act on behalf of the employer accounts associated with that Indeed user account

Unlike the Authorization Code flow (3-Legged OAuth), in this flow, your app is not acting on behalf of another Indeed user; it acts on behalf of itself.

API Authentication

To authenticate to an Indeed API:

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 for your app.

One-time Steps

1. Navigate to the Indeed Application Registration page.
2. Log in to your Indeed account.
3. Click the Register new application button.
4. Enter your Application Name. For example, Ace Recruiters LLC.
5. Select OAuth 2.0.
6. Select Client Credentials.
7. Click the Register button.
8. 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.

Request an access token from the /tokens endpoint using the Client ID and Client Secret from the previous step.

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 'grant_type=client_credentials' \
  -d 'scope=employer_access' \
  -d 'client_id=<your-client_id>' \
  -d 'client_secret=<your-client_secret>' \
  https://apis.indeed.com/oauth/v2/tokens

Example Response

A successful response includes an access token:

{
  "access_token":"eyJraWQiOiI1OTdjYTgxNC0YdVBLkWfA",
  "scope":"employer_access",
  "token_type":"Bearer",
  "expires_in":3600
}

The access token looks like a long garbled string. Note that the response also includes an expires_in field which represents how long the access token is valid, in seconds. The access token expires after 3,600 seconds (one hour), and then you can request a fresh access token again.

Unlike in the case of the Authorization Code flow, you do not get a refresh token nor an ID Token when using the client credentials flow.

Call an Indeed API

Finally, use the access token to call an Indeed API.

When using 2-Legged OAuth (the Client Credentials flow), you can use the AppInfo endpoint to retrieve information about the user who registered the app.

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

URL Path

https://secure.indeed.com/v2/api/appinfo

Use the AppInfo endpoint to get the list of employers associated with the account that registered the app:

curl -H 'Authorization:Bearer eyJraWQiOiI1OTdjYTgxNCImEwzjgselIuEYGlJxsERATA' https://secure.indeed.com/v2/api/appinfo

This query returns a list of employers:

{
   "employers": [
      {
         "id": "084a39249af95beedfb90cc5d2b8833c",
         "name": "Dharma Initiative"
      },
      {
         "id": "865e08b649774436ee1f410b611fad7c",
         "name": "Umbrella Corporation"
      },
      {
         "id": "4bc393648e880bc94dd6cef8efbc8486",
         "name": "US Robotics and Mechanical Men"
      }
   ]
}

You can continue to use the access token for an hour. After an hour, you'll need to request a new access token again, as described in the previous step.

Note: Not all Indeed APIs support the client Credentials flow. Check if the API you're calling supports this flow.

Represent an Employer

When there are multiple employers (advertisers) associated with an Indeed user account, an access token can represent only one employer at a time. An Indeed API might require you to represent a particular employer with an access token. To access such an API, you can build a UI for your users to switch between multiple employer accounts.

To obtain an access token that represents a particular employer:

1. Retrieve an access token with the employer_access scope.
2. Call the AppInfo endpoint to get a list of employers.
3. Enable the user to select an employer from the list of employers.
4. Retrieve a second access token that represents the selected employer.

Step 1: Retrieve an Access Token with the employer_access Scope

The first step is to retrieve an access token with the the employer_access scope.

See get an access token.

Step 2: Call the AppInfo Endpoint to Get a List of Employers

When using 2-Legged OAuth (the Client Credentials flow), you can use the AppInfo endpoint to retrieve information about the user who registered the app.

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

URL Path

https://secure.indeed.com/v2/api/appinfo

Use the AppInfo endpoint to get the list of employers associated with the account that registered the app:

curl -H 'Authorization:Bearer eyJraWQiOiI1OTdjYTgxNCImEwzjgselIuEYGlJxsERATA' https://secure.indeed.com/v2/api/appinfo

This query returns a list of employers:

{
   "employers": [
      {
         "id": "084a39249af95beedfb90cc5d2b8833c",
         "name": "Dharma Initiative"
      },
      {
         "id": "865e08b649774436ee1f410b611fad7c",
         "name": "Umbrella Corporation"
      },
      {
         "id": "4bc393648e880bc94dd6cef8efbc8486",
         "name": "US Robotics and Mechanical Men"
      }
   ]
}

Note that each employer has an id field and a name field. For example, the id field for US Robots and Mechanical Men is 4bc393648e880bc94dd6cef8efbc8486.

Step 3: Enable the User to Select an Employer from the List of Employers

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

Step 4: Retrieve a Second Access Token that Represents the Selected 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.

Example

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' \
  -d 'grant_type=client_credentials' \
  -d 'scope=employer_access' \
  -d 'client_id=b0c3b1092225d3e99f85d7aa3fe1e6001f9a0bb798717cbc2008e58fbda3ef16' \
  -d 'client_secret=1YFoyZOWmr83njlsIuyCL9QQq5jZkRCR4UtmHGp22MRzjIhe5RbynnAGmuYLFbYx' \
  -d 'employer=4bc393648e880bc94dd6cef8efbc8486' \
  https://apis.indeed.com/oauth/v2/tokens

This query returns an access token that represents that employer.

If you attempt to request an employer that is not associated with the user account who registered the OAuth app then you'll get the following error:

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

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