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, other user accounts, or their associated employer accounts.

Some Indeed APIs require additional scopes when you request an access token. For API-specific scopes, see each API's documentation.

To grant your app permissions, 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 when your app calls https://secure.indeed.com/oauth/v2/authorize.

When the user selects Allow for the scopes your app requests (such as employer_access), Indeed sends an authorization code to the redirect_uri with the code and state response fields appended.

Once a user grants a scope, your app keeps it. For example, if your app later needs the employer_access scope, the OAuth consent screen prompts the user only for employer_access — not for email or offline_access.

The authorizing user grants scopes to your app and can revoke them at any time on the Indeed Third-party applications with account access page. The user can grant the scopes again the next time they use the app.

Incremental authorization

Incremental authorization lets OAuth apps request only the scopes they need. It requires the offline_access scope, which preserves the permissions your app already holds. For example, if your app requests the email scope, it must also request offline_access.

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 Lets your app read the user's email and email_verified status from an ID token or the v2/api/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 every employer account associated with the user. 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, so use a refresh token to get a new one. ✔ 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 the query parameters.

Indeed shows the OAuth consent screen to the end user who owns the target account.

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

For an example call, see Get an 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, recommended for confidential clients. The OAuth PKCE code challenge derived from a code verifier per RFC 7636: Proof Key for Code Exchange by OAuth Public Clients. Example: code_challenge=TmosKb_XlmuUDNPfdEPqTNpK5lfA6qWE3OBQHwG_qsc
code_challenge_method	Required when you use PKCE with code_challenge. Only S256 is supported. Example: code_challenge_method=S256
employer	Optional. The employer ID to associate with the access token. You can also pass this parameter when you exchange a refresh token for an access token. Example: employer=6d2f02224e30d401810b1726eb246d8d
prompt	Required. Shows the authorizing user an Indeed employer selection screen, where they pick the employer account to assign to your access token. Add prompt=select_employer 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 page on your site that captures the authorization code. It must match one of the redirect URLs your app registered. Example: Encode https://www.acerecruitersllc.com/oauth/indeed to: https%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed 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. Always code. Example: code
scope	Optional. The permissions your app requests. URL-encode and space-delimit the scopes; encoding turns spaces into plus signs (+). Example: email+offline_access See Scopes.
state	Recommended. Prevents CSRF attacks. Use any unique string your app creates to maintain state between the request and callback. Indeed forwards this value to your redirect URI. Example: employer1234 See 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	The authorization code. Valid for 10 minutes. Example: rXZSMNyYQHQ
state	String	Optional. Indeed returns this field only when you pass it in the request. Example: employer1234

oauth/v2/tokens endpoint

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

For example calls, see:

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

Include these 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 client_id in the request body, 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 client_secret in the request body, pass it in an Authorization header. ✔ 3-legged OAuth ✔ 2-legged OAuth
code	The authorization code to exchange for an access token. To exchange a refresh token instead, use refresh_token. Example: code=rXZSMNyYQHQ ✔ 3-legged OAuth
code_verifier	The code verifier that produced code_challenge. Example: code_verifier=XCojR8eDRqElINajGkYbqX8pQCp6AbPjwAM7Y-8z-UA ✔ 3-legged OAuth, required when you use PKCE
employer	The employer ID to associate with the access token. Example: employer=6d2f02224e30d401810b1726eb246d8d ✔ 2-legged OAuth ✔ 3-legged OAuth
grant_type	Use one of these grant types: client_credentials Get an access token for the Client credentials grant type (2-legged OAuth). authorization_code Get an access token for the Authorization code grant type (3-legged OAuth). refresh_token Refresh an access token for the Authorization code grant type (3-legged OAuth). urn:ietf:params:oauth:grant-type:token-exchange Get an access token for the Token exchange grant type (OAuth). Example: grant_type=client_credentials urn:ietf:params:oauth:grant-type:token-exchange ✔ 3-legged OAuth ✔ 2-legged OAuth ✔ Token exchange OAuth
redirect_uri	The URL-encoded redirect URL. It must match the redirect URL you used when you got the 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	The refresh token to exchange for an access token. Indeed returns the refresh token when you get an access token. To exchange an authorization code instead, use code. Example: refresh_token=rXZSMNyYQHQ ✔ 3-legged OAuth
scope	Conditional. To list the employer accounts associated with the user who registered the app, or to get an access token for one of those accounts, set scope=employer_access. For the Token exchange grant type (OAuth), set scope=openid. See Scopes. Example: scope=employer_access ✔ 3-legged OAuth ✔ 2-legged OAuth
sub	The user's ID in the identity provider. Must map to externalId in SCIM. Example: R1234 ✔ Token exchange OAuth
subject_token	The token that represents the identity of the party the request is made on behalf of. The token issuer must give Indeed a way to validate it. Indeed supports only ID tokens. Example: xxxxx.yyyyy.zzzzz ✔ Token exchange OAuth
subject_token_type	The token type passed in subject_token. Always 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 list of every scope the user has granted your app. Indeed returns this field only when the user grants the offline_access scope. Can include scopes outside the current access token. The scope field lists the scopes in this token. Example: email offline_access
convid	String	The 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	How long the token stays valid, in seconds. Tokens last one hour (3600 seconds). Example: 3600
id_token	String	Your ID token. Example: "eyJraWQiOiJlMzEzZTc4My1lM2YwLTQ3ZWMtY[...] See ID Token.
issued_token_type	String	The type of the issued token. Example: urn:ietf:params:oauth:token-type:access_token
refresh_token	String	Indeed returns a refresh token only when you request the offline_access scope. Store it securely. It expires 60 days after your most recent refresh request. For public clients, Indeed rotates refresh tokens after each use. Example: rXZSMNyYQHQ
scope	String	The space-delimited permissions actually granted to your app, such as email and offline_access. Example: email offline_access See Scopes.
token_type	String	Always Bearer. Example: Bearer

v2/api/appinfo endpoint

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

For an example call, see Build employer selection screen.

Parameters for v2/api/appinfo

This endpoint takes no request body or query parameters.

Response fields for v2/api/appinfo

Response fields for v2/api/appinfo

Response field	Type	Description
employers	Object	The employer accounts associated with the user account that registered the app. Each employer includes the employer ID and name. The user must grant the employer_access scope to view this object.
id	String	The employer ID.
name	String	The employer name.

v2/api/userinfo endpoint

To get account information for the current user, send a GET to https://secure.indeed.com/v2/api/userinfo. The response matches the information in the ID token.

For an example call, see The userinfo endpoint.

Parameters for v2/api/userinfo

This endpoint takes no request body or query parameters.

Response fields for v2/api/userinfo

Response fields for v2/api-userinfo

Response field	Type	Description
email	String	The user's email address. Indeed returns the email and email_verified fields when you request the email scope and the user grants it. Example: mina.ray@myemail.world
email_verified	Boolean	Whether the user has verified their email address. Indeed returns the email and email_verified fields when you request the email scope and the user grants it. Example: true
employers	Object	The employer accounts associated with the user account that registered the app. Each employer includes the employer ID and name. The user must grant the employer_access scope to view this object.
sub	String	The unique identifier for the user's account. Example: 8b5280bdc83ebf66

Error response

See Troubleshoot OAuth errors.

 

Was this page helpful?