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": [ ]
}