CAPTCHAs

As an option to increase org security, Okta supports CAPTCHA services to prevent automated sign-in attempts. You can integrate one of two providers: hCaptcha or reCAPTCHA v2.

The vendor implementations supported by Okta are both invisible. They each run risk-analysis software in the background during user sign in to determine the likelihood that the user is a bot. This risk analysis is based on the settings that you configure with the provider that you choose.

Before you configure your org to use CAPTCHA, sign in to the vendor of your choice or sign up for an account. For more details, refer to CAPTCHA integration.

List all CAPTCHA Instances
Identity Engine
OAuth 2.0: okta.captchas.read

Lists all CAPTCHA instances with pagination support. A subset of CAPTCHA instances can be returned that match a supported filter expression or query.

Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/captchas
Request samples
Response samples
application/json
[
  • {
    • "id": "string",
    • "name": "string",
    • "siteKey": "string",
    • "type": "HCAPTCHA",
    • "_links": {
      }
    }
]

Create a CAPTCHA instance
Identity Engine
OAuth 2.0: okta.captchas.manage

Creates a new CAPTCHA instance. Currently, an org can only configure a single CAPTCHA instance.

Request
Request Body schema: application/json
required
name
string

The name of the CAPTCHA instance

secretKey
string

The secret key issued from the CAPTCHA provider to perform server-side validation for a CAPTCHA token

siteKey
string

The site key issued from the CAPTCHA provider to render a CAPTCHA on a page

type
string (CAPTCHAType)

The type of CAPTCHA provider

Enum: "HCAPTCHA" "RECAPTCHA_V2"
Responses
201

Created

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/captchas
Request samples
application/json
{
  • "name": "myHCaptcha",
  • "secretKey": "xxxxxxxxxxx",
  • "siteKey": "xxxxxxxxxxx",
  • "type": "HCAPTCHA"
}
Response samples
application/json
{}

Retrieve a CAPTCHA Instance
Identity Engine
OAuth 2.0: okta.captchas.read

Retrieves the properties of a specified CAPTCHA instance

Request
path Parameters
captchaId
required
string

The unique key used to identify your CAPTCHA instance

Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/captchas/{captchaId}
Request samples
Response samples
application/json
{}

Update a CAPTCHA Instance
Identity Engine
OAuth 2.0: okta.captchas.manage

Partially updates the properties of a specified CAPTCHA instance

Request
path Parameters
captchaId
required
string

The unique key used to identify your CAPTCHA instance

Request Body schema: application/json
required
name
string

The name of the CAPTCHA instance

secretKey
string

The secret key issued from the CAPTCHA provider to perform server-side validation for a CAPTCHA token

siteKey
string

The site key issued from the CAPTCHA provider to render a CAPTCHA on a page

type
string (CAPTCHAType)

The type of CAPTCHA provider

Enum: "HCAPTCHA" "RECAPTCHA_V2"
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/captchas/{captchaId}
Request samples
application/json
{
  • "name": "myHCaptcha",
  • "secretKey": "xxxxxxxxxxx",
  • "siteKey": "xxxxxxxxxxx",
  • "type": "HCAPTCHA"
}
Response samples
application/json
{}

Replace a CAPTCHA Instance
Identity Engine
OAuth 2.0: okta.captchas.manage

Replaces the properties for a specified CAPTCHA instance

Request
path Parameters
captchaId
required
string

The unique key used to identify your CAPTCHA instance

Request Body schema: application/json
required
name
string

The name of the CAPTCHA instance

secretKey
string

The secret key issued from the CAPTCHA provider to perform server-side validation for a CAPTCHA token

siteKey
string

The site key issued from the CAPTCHA provider to render a CAPTCHA on a page

type
string (CAPTCHAType)

The type of CAPTCHA provider

Enum: "HCAPTCHA" "RECAPTCHA_V2"
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/captchas/{captchaId}
Request samples
application/json
{
  • "name": "myHCaptcha",
  • "secretKey": "xxxxxxxxxxx",
  • "siteKey": "xxxxxxxxxxx",
  • "type": "HCAPTCHA"
}
Response samples
application/json
{}

Delete a CAPTCHA Instance
Identity Engine
OAuth 2.0: okta.captchas.manage

Deletes a specified CAPTCHA instance

Note: If your CAPTCHA instance is still associated with your org, the request fails. You must first update your Org-wide CAPTCHA settings to remove the CAPTCHA instance.

Request
path Parameters
captchaId
required
string

The unique key used to identify your CAPTCHA instance

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/captchas/{captchaId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Retrieve the Org-wide CAPTCHA Settings
Identity Engine
OAuth 2.0: okta.captchas.read

Retrieves the CAPTCHA settings object for your organization.

Note: If the current organization hasn't configured CAPTCHA Settings, the request returns an empty object.

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/org/captcha
Request samples
Response samples
application/json
{}

Replace the Org-wide CAPTCHA Settings
Identity Engine
OAuth 2.0: okta.captchas.manage

Replaces the CAPTCHA settings object for your organization.

Note: You can disable CAPTCHA for your organization by setting captchaId and enabledPages to null.

Request
Request Body schema: application/json
required
captchaId
string

The unique key of the associated CAPTCHA instance

enabledPages
Array of strings (enabledPages)

An array of pages that have CAPTCHA enabled

Items Enum: Description
SIGN_IN

User sign-in page

SSPR

Self-service Password Recovery page

SSR

Self-service Registration page

Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

put/api/v1/org/captcha
Request samples
application/json
{
  • "captchaId": "abcd4567",
  • "enabledPages": [
    • "SSR",
    • "SIGN_IN"
    ]
}
Response samples
application/json
{}

Delete the Org-wide CAPTCHA Settings
Identity Engine
OAuth 2.0: okta.captchas.manage

Deletes the CAPTCHA settings object for your organization

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/org/captcha
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}