Client Credentials Flow (2-legged OAuth)

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:

# Step Step Frequency
1. Get a Client ID and Secret One time only
2. Get an Access Token For each app
3. Call an Indeed API With each API call

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:

Header Value
Content-Type application/x-www-form-urlencoded
Accept application/json

Fields

Name Required Description Example
client_id Conditional Your client ID. Instead of sending your client_id in the request, you can choose to pass it in an Authorization Header. 6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b
client_secret Conditional Your client secret. Instead of sending your client_secret in the request, you can choose to pass it in an Authorization Header. 02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv
grant_type Required Must be client_credentials. client_credentials
scope Conditional To get a list of employer accounts associated with the user that registered the app or to get an access token for one of these associated employer accounts, pass employer_access. employer_access
Warning: When calling the /v2/tokens endpoint, you must use an HTTP POST request and you must pass all of the fields above, such as the client_secret field, in the request body. Do not pass any of these fields as query string parameters.

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.

Name Consent String Description
employer_access List the employers associated with a user account and/or 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. To retrieve a list of employers, see Represent an Employer.