OAuth reference

HTTP request headers, scopes, and API endpoints with request parameters and response fields.

 

legal notice

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

HTTP request headers

The request headers are:

Header	Value and description
Accept	application/json
Authorization	Bearer <access_token> In each API call, pass the access token in this header with the Bearer authentication scheme. You can pass the Authorization header only when you request or refresh an access token through the oauth/v2/tokens endpoint. When you get an access token, you can use the basic authentication scheme instead of passing your client ID and secret in the oauth/v2/tokens request body. See also access token and basic authentication scheme.
Content-Type	application/x-www-form-urlencoded

Basic authentication scheme

When you get an access token, you can use the basic authentication scheme instead of passing your client ID and secret in the /oauth/v2/tokens request body. To use this scheme, you encode and pass these credentials in an Authorization Basic header.

See also Basic Authentication Scheme in RFC2617: HTTP Authentication: Basic and Digest Access Authentication.

To generate the Authorization Basic header value:

1. Concatenate the client_id and client_secret with a colon (:) as a separator.

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

2. Apply the Base64-encoding algorithm to the string:

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

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

   Authorization: Basic NWUxNzVjYmI3Zjg4ZTIwNDhiZDk1MzIzYmJjOWNhMmZjZWMzMmFkNjBmOTVmN2VlNjZhYjUzZTA5OWFiZTZmMzpwSjRxUmUyc2RYUlAwV2hyM2J3ejlEMzdleEZ1dU90cUpEUkhNbW1sTFdWN0oyNXJIN29JdHJQTkNLemhhUWYy

Scopes

Scopes authorize your app to act on behalf of itself, or other user accounts, and associated employer accounts.

Some Indeed APIs have additional scopes that you must pass when you request the access token. For API-specific scopes, see the API documentation for each API.

To request scopes that grant permissions to your app, include the scope parameter when you get an access token.

OAuth consent screen

For the authorization code flow (3-legged OAuth), Indeed shows the OAuth consent screen to the user in response to the https://secure.indeed.com/oauth/v2/authorize call.

If the user selects Allow to authorize any scopes that the OAuth app requests, such as the employer_access scope, Indeed passes an authorization code to the redirect_uri with the code and state response fields appended.

After a user grants your app a scope, they do not need to grant the scope again. For example, if the user requests functionality from your app that requires the employer_access scope, the OAuth consent screen prompts the user to grant only the employer_access scope, and not the email and offline_access scopes.

For the authorization code flow (3-legged OAuth), the authorizing user grants scopes to your app. A user can revoke all scopes from an app through the Indeed Third-party applications with account access page. When using the app, the user can grant scopes again.

Incremental authorization

Incremental authorization enables OAuth apps to request only the scopes that they need, and requires the offline_access, which maintains the permissions that your app has. For example, if your app requests the email scope, your app must also request the offline_access scope.

Granted scopes

The consented_scope field in the oauth/v2/tokens response lists the app's granted scopes:

{
  "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
}

Additionally, for authorization code flow (3-legged OAuth), the Current permissions tab on the OAuth consent screen lists the app's scopes.

Scope	Permissions
email	Consent screen: View your email address When calling the v2/api/userinfo endpoint, 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. See The userinfo endpoint. ✔ 3-legged OAuth
employer_access	Consent screen: List employers associated with a user account and get an access token for an employer Lists all employer accounts associated with the user and is required to get an access token for an employer. To list employers and get an access token for an employer: For 3-legged authorization, see Get access token that represents employer. For 2-legged authorization, see Get access token that represents employer. ✔ 3-legged OAuth ✔ 2-legged OAuth
offline_access	Consent screen: Maintain the permissions that you have granted Required to generate a refresh token. Indeed OAuth access tokens expire after one hour. To get an access token, use a refresh token. ✔ 3-legged OAuth

oauth/v2/authorize endpoint

To get an authorization code for the authorization code flow (3-legged OAuth), call the https://secure.indeed.com/oauth/v2/authorize endpoint with query parameters.

In response to this call, Indeed shows the OAuth consent screen to the user. If the user selects Allow, Indeed passes an authorization code to the redirect_uri with the code and state response fields appended. See Response fields for oauth/v2/authorize.

For an example call, see Get authorization code.

Query parameters for oauth/v2/authorize

This endpoint and these query parameters apply to 3-legged OAuth only:

Query parameter	Required	Description
client_id	✔	Client ID. Examples: 6nwwcdklwgktryjw2j5f xh5t2fyneule7zg7mvw3pf9 jbx3wmewzlxkdz1jxvs6b
code_challenge	✔ for public clients	Recommended for confidential clients OAuth PKCE code challenge generated from code verifier in RFC7636: Proof Key for Code Exchange by OAuth Public Clients. Example: code_challenge=TmosKb_XlmuUDNPfdEPqTNpK5lfA6qWE3OBQHwG_qsc
code_challenge_method	✔ if PKCE is used with code_challenge	Only S256 is supported. Example: code_challenge_method=S256
employer		An employer ID to associate with an access token. You can also use this parameter when you exchange a refresh token for an access token. Example: employer=6d2f02224e30d401810b1726eb246d8d
prompt		Prompts the authorizing user with an Indeed employer selection screen, from which the user chooses the employer account assigned to your access token. To do this, add the prompt=select_employer parameter to the authorization link, and include the employer_access scope. Example: prompt=select_employer See Show the Indeed employer selection screen.
redirect_uri	✔	URL-encoded redirect URL. Identifies the redirect page on your site where you capture the authorization code. It must match one of the redirect URLs that your app registers. Example: Encode https://www.acerecruitersllc.com/oauth/indeed to: https%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed%3Fmy-param%3Dpass-me-this-value See Ask Indeed to register your app. See also Do not append query parameters to the redirect URI.
response_type	✔	Value is always code. Example: code
scope		Permissions that the client app requests. You must URL-encode and space-delimit scopes, which replaces the spaces with plus signs ( +). Example: email+offline_access See Scopes.
state	Recommended	Prevents CSRF attacks. Can be any unique string your app creates to maintain state between the request and callback. Indeed passes this parameter to your redirect URI. Example: employer1234 See also Threat: CSRF Attack against redirect-uri in RFC6819: OAuth 2.0 Threat Model and Security Considerations.

Response fields for oauth/v2/authorize

Response field	Type	Description
code	String	Authorization code. Valid for 10 minutes. Example: rXZSMNyYQHQ
state	String	Optional. Appears only if you pass it in the request. Example: employer1234

oauth/v2/tokens endpoint

Exchange your OAuth credentials for an access token.

Make a POST request to the https://apis.indeed.com/oauth/v2/tokens endpoint.

For example calls, see:

• Get or refresh 2-legged access token
• Get 3-legged access token
• Refresh 3-legged access token

Include the following request body parameters:

Request body parameters for oauth/v2/tokens

Request body parameter	Required for OAuth flow	Description
client_id	✔ 3-legged OAuth ✔ 2-legged OAuth	Your client ID. Example: 6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b Instead of sending your client_id in the request, you can pass it in an Authorization header.
client_secret	✔ 3-legged OAuth ✔ 2-legged OAuth	Your client secret. Omit for public clients. Example: 02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv Instead of sending your client_secret in the request, you can pass it in an Authorization header.
code	✔ 3-legged OAuth, to exchange authorization code for access token	An authorization code to exchange for an access token. To exchange a refresh token for an access token, specify refresh_token instead. Example: rXZSMNyYQHQ
code_verifier	If PKCE is used ✔ 3-legged OAuth	The code verifier that generates code_challenge. Example: code_verifier=XCojR8eDRqElINajGkYbqX8pQCp6AbPjwAM7Y-8z-UA
employer	✔ 2-legged OAuth ✔ 3-legged OAuth	An employer ID to associate with an access token. Example: employer=6d2f02224e30d401810b1726eb246d8d
grant_type	✔ 3-legged OAuth ✔ 2-legged OAuth	Depending on the grant type that you selected during registration, this value is: Grant type Value Client credentials client_credentials Authorization code To get an access token: authorization_code To refresh an access token: refresh_token Examples: client_credentials authorization_code refresh_token
redirect_uri	✔ 3-legged OAuth	URL-encoded redirect URL. Must match the redirect URL you specified when you got an authorization code. Example: Encode https://www.acerecruitersllc.com/oauth/indeed to: https%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed%3Fmy-param%3Dpass-me-this-value See Get an authorization code.
refresh_token	✔ 3-legged OAuth, to exchange refresh token for access token	Refresh token to exchange for an access token. The refresh token is returned when you get an access token. To exchange an authorization code for an access token, specify code instead. Example: rXZSMNyYQHQ
scope	Conditional ✔ 3-legged OAuth ✔ 2-legged OAuth	To list 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. See Scopes. Example: employer_access

Response fields for oauth/v2/tokens

Response field	Type	Description
access_token	String	Your access token. Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikpv[...]
consented_scope	String	A space-delimited string of all scopes that the user has granted to your app. This field appears only if the user grants the offline_access scope. Can include scopes that are not in this current access token. Scopes in that token are represented by the scope field. Example: email offline_access
convid	String	Conversation identifier. Example: "convid": "1eis1tplg01fe802"
error	String	The error type. Example: "error": "invalid_request"
error_description	String	A description of the error. Example: "error_description": "Invalid authentication request."
expires_in	Integer	Token is valid for one hour (3600 seconds). Example: 3600
id_token	String	Your ID token. Example: "eyJraWQiOiJlMzEzZTc4My1lM2YwLTQ3ZWMtY[...] See ID Token.
refresh_token	String	You get a refresh token only when you request the offline_access scope. Store this securely. It expires 60 days after your most recent refresh request. For public clients, refresh tokens are rotated after use. Example: rXZSMNyYQHQ
scope	String	The actual permissions granted to your app. For example, email and offline_access scopes. Scopes are space-delimited. Example: email offline_access See Scopes.
token_type	String	Value is always Bearer. Example: Bearer

v2/api/appinfo endpoint

To list employers associated with the user account that registered the app, call the https://secure.indeed.com/v2/api/appinfo endpoint with the access token in the Authorization header with the Bearer authentication scheme.

For an example call, see Build employer selection screen.

Parameters for v2/api/appinfo

This endpoint has no request body or query parameters.

Response fields for v2/api/appinfo

Response field	Type	Description
employers	Object	List of employer accounts associated with the user account that registered the app. Each employer shows the employer ID and employer name. To view this object, the user must grant the employer_access scope.
id	String	ID of employer.
name	String	Name of employer.

v2/api/userinfo endpoint

To get account information for the current user, call the https://secure.indeed.com/v2/api/userinfo endpoint, which returns the same information that the ID token returns.

For an example call, see The userinfo endpoint.

Parameters for v2/api/userinfo

This endpoint has no request body or query parameters.

Response fields for v2/api/userinfo

Response field	Type	Description
email	String	User's email address. If you request the email scope and the user grants it, the response shows the email and email_verified fields. Example: mina.ray@myemail.world
email_verified	Boolean	Indicates whether the user has verified their email address. If you request the email scope and the user grants it, the response shows the email and email_verified fields. Example: true
employers	Object	List of employer accounts associated with the user account that registered the app. Each employer shows the employer ID and employer name. To view this object, the user must grant the employer_access scope.
sub	String	Unique identifier for the user's account. Example: 8b5280bdc83ebf66

Error response

See Troubleshoot OAuth errors.