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:

HTTP request headers

Header	Value and description
Accept	application/json
Authorization	Bearer <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/json

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 RFC 2617: 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 grant type (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 grant type (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": "<access_token>",
  "refresh_token": "<refresh_token>",
  "id_token": "<id_token>",
  "scope": "offline_access employer_access email",
  "consented_scope": "offline_access employer_access email",
  "convid": "1er835qvtu54n800",
  "token_type": "Bearer",
  "expires_in": 3600
}

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

Application 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 grant type (3-legged OAuth), call the https://secure.indeed.com/oauth/v2/authorize endpoint with query parameters.

Indeed shows the OAuth consent screen to the end user that owns the account to which you want access.

If the end user selects Allow, Indeed passes an authorization code to the redirect_uri with the code and state response fields appended.

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 parameters for oauth/v2/authorize

Query parameter	Description
client_id	Required. The client ID. Examples: 6nwwcdklwgktryjw2j5f xh5t2fyneule7zg7mvw3pf9 jbx3wmewzlxkdz1jxvs6b
code_challenge	Required for public clients, and recommended for confidential clients. The OAuth PKCE code challenge generated from code verifier in RFC 7636: Proof Key for Code Exchange by OAuth Public Clients. Example: code_challenge=TmosKb_XlmuUDNPfdEPqTNpK5lfA6qWE3OBQHwG_qsc
code_challenge_method	Required if PKCE is used with code_challenge. Only S256 is supported. Example: code_challenge_method=S256
employer	Optional. 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	Required. 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	Required. The 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 caution Although Indeed supports query parameters in the redirect_uri parameter, Indeed encourages you to use the state parameter instead. See also the state parameter.
response_type	Required. The value is always code. Example: code
scope	Optional. The 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 RFC 6819: OAuth 2.0 Threat Model and Security Considerations.

Response fields for oauth/v2/authorize

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

To exchange your client ID and secret for an access token, POST to the https://apis.indeed.com/oauth/v2/tokens endpoint with Accept and Content-Type request headers, and request body parameters.

For example calls, see:

• Get 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 parameters for oauth/v2/tokens

Request body parameter	Description
client_id	Your client ID. Example: client_id=6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b Instead of sending your client_id in the request, you can pass it in an Authorization header. ✔ 3-legged OAuth ✔ 2-legged OAuth
client_secret	Your client secret. Omit for public clients. Example: client_secret=02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv Instead of sending your client_secret in the request, you can pass it in an Authorization header. ✔ 3-legged OAuth ✔ 2-legged OAuth
code	An authorization code to exchange for an access token. To exchange a refresh token for an access token, specify refresh_token instead. Example: code=rXZSMNyYQHQ ✔ 3-legged OAuth
code_verifier	The code verifier that generates code_challenge. Example: code_verifier=XCojR8eDRqElINajGkYbqX8pQCp6AbPjwAM7Y-8z-UA ✔ 3-legged OAuth, required if PKCE is used
employer	An employer ID to associate with an access token. Example: employer=6d2f02224e30d401810b1726eb246d8d ✔ 2-legged OAuth ✔ 3-legged OAuth
grant_type	✔ 3-legged OAuth ✔ 2-legged OAuth ✔ Token exchange OAuth The valid grant types are: client_credentials Get access token for Client credentials grant type (2-legged OAuth). authorization_code Get access token for Authorization code grant type (3-legged OAuth). refresh_token Refresh an access token for Authorization code grant type (3-legged OAuth). urn:ietf:params:oauth:grant-type:token-exchange Get access token for Token exchange grant type (OAuth). Example: grant_type=client_credentials urn:ietf:params:oauth:grant-type:token-exchange
redirect_uri	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. Then set: redirect_uri=https%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed%3Fmy-param%3Dpass-me-this-value See Get an authorization code. ✔ 3-legged OAuth
refresh_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: refresh_token=rXZSMNyYQHQ ✔ 3-legged OAuth
scope	To list employer accounts associated with the user that registered the app or to get an access token for an associated employer account, set scope=employer_access. See Scopes. Example: scope=employer_access 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. For the Token exchange grant type (OAuth), value is openid. See Scopes. Example: employer_access
sub	User's ID in the identity provider. Must map to externalId in SCIM. Example: R1234 ✔ Token exchange OAuth
subject_token	Token that represents the identity of the party on behalf of whom the request is being made. The issuer of the token must provide some ways for Indeed to validate the token. Indeed supports only ID tokens. Example: xxxxx.yyyyy.zzzzz ✔ Token exchange OAuth
subject_token_type	Type of token passed in the subject_token field. Value is urn:ietf:params:oauth:token-type:id_token. Example: urn:ietf:params:oauth:token-type:id_token ✔ Token exchange OAuth

Response fields for oauth/v2/tokens

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.
issued_token_type	String	The token type of the issued token. Example: urn:ietf:params:oauth:token-type:access_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 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, make a GET request to 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 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.

 

Was this page helpful?