Client credentials flow (2-legged OAuth)

📘

Note:

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

Client credentials flow (2-legged OAuth) overview

📘

Notes:

• For an overview of Indeed authentication, see Indeed authentication.

• Not all Indeed APIs support the client credentials flow (2-legged OAuth).

Authorize your app to act on behalf of the Indeed account that registers your app to get client ID and secret credentials.

To use this flow, complete these steps:

See also Additional tasks.

Step 1. Register your app

Register your app to get a client ID and secret, which identify your app.

1. On the Manage app credentials page, sign in to your Indeed account, then click Register new application.

2. Enter your app name and description, select the OAuth 2.0 credential type, then click Save and continue.

   📘 Notes:

   • Register both test and production versions of an app to generate separate API credentials. During registration, add these suffixes to their names:

     • -dev to test apps. For example, AceRecruitersApp-dev.
     • -prod to production apps. For example, AceRecruitersApp-prod.

   • The Indeed Apply credential type is for Indeed Apply integrations only.

3. Select the Client credentials grant type, then click Save and continue.

4. Optionally, provide additional company information, then click Save and continue.

5. Preview your app information, then click Complete registration.

   The page shows information about your app, including the client ID and secret.

   Example

   Client ID:        6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b
   Secrets:          02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv
   Application name: Ace Recruiters LLC

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

Step 2. Get an access token

Exchange your client ID and secret for an access token, which you include in each API call to prove that your app is authorized to make calls on behalf of the Indeed account that the token identifies.

To get an access token, make a POST request to the https://apis.indeed.com/oauth/v2/tokens endpoint with the Content-Type and Accept request headers, and all request body parameters that the following example shows:

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

The response shows the access token, scope, token type, and the expires_in field, which indicates the duration, in seconds, that the access token is valid.

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

See Response fields for oauth/v2/tokens.

As the example shows, the access token expires in 3600 seconds, or one hour.

Step 3. Refresh your access token

Access tokens are valid for one hour.

Unlike the authorization code flow (3-legged OAuth), the client credentials flow (2-legged OAuth) response does not include a refresh token or an ID token.

To get a new access token, exchange your client ID and secret for one.

Step 4. Call an Indeed API

To call an Indeed API, include your access token.

1. In each API call, pass the access token in the Authorization header with the Bearer authentication scheme.

   For example:

   Shell

   Authorization: Bearer <access-token>
   

2. To get information about the user who registered the app, use the v2/api/appinfo endpoint.

   For example, to list employers associated with the account that registered the app:

   cURL

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

   The response lists employers:

   JSON

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

3. After an hour, get a new access token.

Additional tasks

Enable user to select an employer

An Indeed API might require you to represent an employer with an access token. An access token represents only one employer. You can build a UI that enables users to switch between employer accounts.

To get an access token for an employer:

1. Get an access token with the employer_access scope.

2. To list employers associated with the user account that registered the app, call the appinfo endpoint with the access token in the Authorization header with the Bearer authentication scheme:

   cURL

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

   The response shows id and name fields for each employer.

   For example, the id field for US Robots and Mechanical Men is 4bc393648e880bc94dd6cef8efbc8486:

   JSON

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

3. Build a user interface that lists employers so that the user can select one.

4. Use the ID of the employer that the user selects to get an access token that represents that employer.

   To do this, pass the employer ID in the employer parameter of the oauth/v2/tokens endpoint:

   cURL

   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 request returns an access token that represents that employer.

   📘

   Note:

   If you request an access token for an employer that is not associated with the user account who registered the OAuth app, the following error occurs:

   JSON

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

Authorize an app to act on your behalf

In this flow, use the Indeed Users page to authorize an app to act on your behalf or remove that authorization.

1. On the Indeed Users page, select an employer account, then click Add users.

2. Enter the user's email address and select the level of access, then click Save and notify new users.

   The user receives an email invitation to join your organization on Indeed. If they accept, they are granted the selected permissions.

If another company wants to act on your behalf, they need your employer ID, which appears in a small font above the page footer on the Indeed Users page. The employer ID is not secret, so you can share it with other companies.

See also