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. When you request or refresh an access token through the `oauth/v2/tokens` endpoint, you can instead pass your client ID and secret in this header with the basic authentication scheme, rather than in the request body. See also access token and basic authentication scheme.
`Content-Type`	`application/json` When you request or refresh an access token through the `oauth/v2/tokens` endpoint, use `application/x-www-form-urlencoded` instead.

Basic authentication scheme

When you get an access token, you can pass your client ID and secret in an Authorization: Basic header instead of in the /oauth/v2/tokens request body.

See also Basic Authentication Scheme (opens in a new window) in RFC 2617: HTTP Authentication: Basic and Digest Access Authentication.

To generate the Authorization Basic header value:

Concatenate the client_id and client_secret with a colon (:) as a separator.
```
base64.encode("<client_id>:<client_secret>");
```

Apply the Base64-encoding algorithm to the string:

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

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

Authorization: Basic NWUxNzVjYmI3Zjg4ZTIwNDhiZDk1MzIzYmJjOWNhMmZjZWMzMmFkNjBmOTVmN2VlNjZhYjUzZTA5OWFiZTZmMzpwSjRxUmUyc2RYUlAwV2hyM2J3ejlEMzdleEZ1dU90cUpEUkhNbW1sTFdWN0oyNXJIN29JdHJQTkNLemhhUWYy

Scopes

Scopes let your app act for itself, for other user accounts, or for the employer accounts associated with them.

For 3-legged OAuth, include the requested scopes in the scope parameter of the /oauth/v2/authorize request before consent. For 2-legged OAuth, include the scope parameter when required, such as scope=employer_access when getting a token for an employer account. Some Indeed APIs need extra scopes; see each API's documentation.

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 and appends the code, iss, and state response fields. See Response fields for oauth/v2/authorize.

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

The user can revoke granted scopes at any time on Indeed's Third-party applications with account access (opens in a new window) page. The user can grant the scopes again the next time they use the app.

Incremental authorization

Incremental authorization lets OAuth apps request scopes only when they need them. It requires the offline_access scope, which keeps the permissions your app already has. For example, if your app requests email, 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
}

For 3-legged OAuth, the Current permissions tab on the OAuth consent screen also lists them.

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 OAuth, see Get access token that represents employer. For 2-legged OAuth, 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.

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 (opens in a new window). 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`	Optional. 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` Indeed accepts query parameters in `redirect_uri`, but pass values in the `state` parameter instead.
`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 keep state between the request and the callback. Indeed passes this value back to your redirect URI. Example: `employer1234` See Threat: CSRF Attack against redirect-uri (opens in a new window) 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`
`iss`	String	The authorization server's issuer ID, such as `https://secure.indeed.com`. Indeed always returns this value in both successful and error responses (RFC 9207 (opens in a new window)). If you integrate only with Indeed, you can ignore it. If your client connects to multiple authorization servers, verify that the value matches Indeed's expected issuer to protect against mix-up attacks. Indeed declares support through `authorization_response_iss_parameter_supported` in `/.well-known/openid-configuration`. Example: `https%3A%2F%2Fsecure.indeed.com`
`state`	String	Returned only when you pass `state` in the request. Example: `employer1234`

oauth/v2/tokens endpoint

To get or refresh an access token, send a POST to https://apis.indeed.com/oauth/v2/tokens with the Accept: application/json and Content-Type: application/x-www-form-urlencoded headers and the request body parameters.

For example calls, see:

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` You can pass it in the `Authorization` header instead of the request body. 3-legged OAuth 2-legged OAuth Token exchange OAuth
`client_secret`	Your client secret. Omit for public clients. Example: `client_secret=02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv` You can pass it in the `Authorization` header instead of the request body. 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` 3-legged OAuth 2-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` `grant_type=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` 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), `scope` is optional. Set it to the scopes required by your integration, such as `scope=email offline_access` or `scope=openid`. See Scopes. Example: `scope=employer_access` 2-legged OAuth Token exchange 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 identifies the party you're making the request for. 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. It can include scopes that aren't in 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 (opens in a new window).
`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	A space-delimited list of the scopes in this access token, such as `email` and `offline_access`. Example: `email offline_access`
`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 and pass the access token in the Authorization header with the Bearer scheme.

For an example call, see Build 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.

Parameters for v2/api/userinfo