On this page

CAPTCHAS API

Identity Engine

Note: This feature is only available as a part of Okta Identity Engine. Contact support for further information.

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 (opens new window) or reCAPTCHA v2 (opens new window).

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.

The Okta CAPTCHAs API provides operations to manage CAPTCHAs and Org-wide CAPTCHA Settings.

Get started

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 (opens new window).

Explore the CAPTCHAs API: Run in Postman (opens new window)

CAPTCHA operations

The CAPTCHAs API has the following CRUD operations:

Create CAPTCHA

POST /api/v1/captchas

Creates a CAPTCHA object

Note: One organization can have only one CAPTCHA provider configured at a time.

Request path parameters

N/A

Request query parameters

N/A

Request body

The CAPTCHA

Response body

Returns a CAPTCHA Response.

Use example

This request creates a CAPTCHA object:

Request
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "myReCaptcha",
  "siteKey": "copy_your_site_key",
  "secretKey": "copy_your_secret_key",
  "type": "RECAPTCHA_V2"
}' "https://${yourOktaDomain}/api/v1/captchas"
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
  "id": "cap18c2Ey3iR9BLDb0g4",
  "name": "myReCaptcha",
  "siteKey": "6LeVzVIaAAAAAHCbhZ-uxTihGl7iuufxEF_dMH-x",
  "type": "RECAPTCHA_V2",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
      "hints": {
        "allow": [
          "GET",
          "POST",
          "PUT",
          "DELETE"
        ]
      }
    }
  }
}

Error example

The following request returns an error when the org already has a CAPTCHA.

Request
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "myReCaptcha2",
  "siteKey": "copy_your_site_key",
  "secretKey": "copy_your_secret_key",
  "type": "RECAPTCHA_V2"
}' "https://${yourOktaDomain}/api/v1/captchas"
Response
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "errorCode": "E0000166",
  "errorSummary": "CAPTCHA count limit reached. At most one CAPTCHA instance is allowed per Org. Please remove existing CAPTCHA to create a new one.",
  "errorLink": "E0000166",
  "errorId": "oaeujx4SxU6S-Gc6HvPnpG2MQ",
  "errorCauses": [
    {
      "errorSummary": "CAPTCHA count limit reached. At most one CAPTCHA instance is allowed per Org. Please remove existing CAPTCHA to create a new one.",
      "reason": "EXCEEDS_MAX_VALUE",
      "locationType": "url",
      "domain": "captcha"
    }
  ]
}

Get CAPTCHA

GET /api/v1/captchas/${id}

Fetches a CAPTCHA by id

Request path parameters

Parameter Type Description
id String (URL) ID of a CAPTCHA

Request query parameters

N/A

Request body

N/A

Response body

The requested CAPTCHA Response

Use example

The following example returns a CAPTCHA object by ID:

Request
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/captchas/{id}"
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "cap18c2Ey3iR9BLDb0g4",
  "name": "myReCaptcha",
  "siteKey": "6LeVzVIaAAAAAHCbhZ-uxTihGl7iuufxEF_dMH-x",
  "type": "RECAPTCHA_V2",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
      "hints": {
        "allow": [
          "GET",
          "POST",
          "PUT",
          "DELETE"
        ]
      }
    }
  }
}

Get all CAPTCHAs

GET /api/v1/captchas

List all CAPTCHAs for the org

Request path parameters

N/A

Request query parameters

N/A

Request body

N/A

Response body

Array of the CAPTCHA Response

Use example

The following example returns all CAPTCHAs in the org.

Note: Currently, only one CAPTCHA per org is supported.

Request
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/captchas"
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": "cap18c2Ey3iR9BLDb0g4",
    "name": "myReCaptcha",
    "siteKey": "6LeVzVIaAAAAAHCbhZ-uxTihGl7iuufxEF_dMH-x",
    "type": "RECAPTCHA_V2",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
        "hints": {
          "allow": [
            "GET",
            "POST",
            "PUT",
            "DELETE"
          ]
        }
      }
    }
  }
]

Update CAPTCHA

PUT /api/v1/captchas/${id}

POST /api/v1/captchas/${id}

Updates a CAPTCHA by id

Note: Use the POST method for partial updates.

Request path parameters

Parameter Type Description
id String (URL) ID of a CAPTCHA

Request query parameters

N/A

Request body

The CAPTCHA

Response body

Returns an updated CAPTCHA Response

Use example

The following example fully updates a CAPTCHA with the PUT method.

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "myReCaptcha",
  "siteKey": "copy_your_site_key",
  "secretKey": "copy_your_secret_key",
  "type": "RECAPTCHA_V2"
}' "https://${yourOktaDomain}/api/v1/captchas/{id}"
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "cap18c2Ey3iR9BLDb0g4",
  "name": "myReCaptcha",
  "siteKey": "6LeVzVIaAAAAAHCbhZ-uxTihGl7iuufxEF_dMH-x",
  "type": "RECAPTCHA_V2",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
      "hints": {
        "allow": [
          "GET",
          "POST",
          "PUT",
          "DELETE"
        ]
      }
    }
  }
}

The following example partially updates a CAPTCHA with the POST method.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "siteKey": "new_site_key",
  "secretKey": "new_secret_key"
}' "https://${yourOktaDomain}/api/v1/captchas/{id}"
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "cap18c2Ey3iR9BLDb0g4",
  "name": "myReCaptcha",
  "siteKey": "new_site_key",
  "type": "RECAPTCHA_V2",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
      "hints": {
        "allow": [
          "GET",
          "POST",
          "PUT",
          "DELETE"
        ]
      }
    }
  }
}

Delete CAPTCHA

DELETE /api/v1/captchas/${id}

Permanently deletes a CAPTCHA

Note: If the CAPTCHA is associated with Org-wide CAPTCHA Settings, you can't remove it before it's unassociated with the Org-wide CAPTCHA Settings.

Request path parameters

Parameter Type Description
id String (URL) ID of a CAPTCHA

Request query parameters

N/A

Request body

N/A

Response body

N/A

Usage example

The following request deletes a CAPTCHA with the specified id.

Request
curl -v -X DELETE \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/captcha/{id}"
Response
HTTP/1.1 204 No Content
Content-Type: application/json

Error example

The following request returns an error because the CAPTCHA is associated with Org-wide CAPTCHA Settings.

Request
curl -v -X DELETE \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/captcha/{id}"
Response
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
    "errorCode": "E0000168",
    "errorSummary": "CAPTCHA cannot be removed. This CAPTCHA is associated with org-wide CAPTCHA settings, please disassociate it before removing it.",
    "errorLink": "E0000168",
    "errorId": "oaeFlwI593rRXmCrGdppDyyJg",
    "errorCauses": [
        {
            "errorSummary": "CAPTCHA cannot be removed. This CAPTCHA is associated with org-wide CAPTCHA settings, please disassociate it before removing it.",
            "reason": "PROHIBITED",
            "locationType": "url",
            "domain": "captcha"
        }
    ]
}

CAPTCHA API objects

CAPTCHA object

CAPTCHA properties

The CAPTCHA object defines the following properties:

Property Type Description
name String Name of CAPTCHA
siteKey String Site key issued from the CAPTCHA vendor to render a CAPTCHA on a page
secretKey String Secret key issued from the CAPTCHA vendor to perform server-side validation for a CAPTCHA token
type String Type of CAPTCHA. Supported values: HCAPTCHA and RECAPTCHA_V2

CAPTCHA example

{
  "name": "myHCaptcha",
  "siteKey": "copy_your_site_key",
  "secretKey": "copy_your_secret_key",
  "type": "HCAPTCHA"
}

CAPTCHA Response object

CAPTCHA Response properties

The CAPTCHA object defines the following properties:

Property Type Description
id String Unique key for the CAPTCHA
name String Name of the CAPTCHA
siteKey String Site key issued from the CAPTCHA vendor to render a CAPTCHA on a page
type HCAPTCHA, RECAPTCHA_V2 Type of CAPTCHA
_links Links Link relations for this object

CAPTCHA example

{
  "id": "cap18c2Ey3iR9BLDb0g4",
  "name": "myReCaptcha",
  "siteKey": "your_site_key",
  "type": "RECAPTCHA_V2",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
      "hints": {
        "allow": [
          "GET",
          "POST",
          "PUT",
          "DELETE"
        ]
      }
    }
  }
}

Specifies link relations (see Web Linking (opens new window)) available for the current status of an application using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and lifecycle operations. The Links object is read-only.

Org-wide CAPTCHA Settings operations

The Org-wide CAPTCHA Settings are used to configure which parts of the authentication flow requires users to pass the CAPTCHA logic.

The Org-wide CAPTCHA Settings API has the following operations:

Get Org-wide CAPTCHA Settings

GET /api/v1/org/captcha

Fetch Org-wide CAPTCHA Settings

Note: If there's no Org-wide CAPTCHA Settings in the current org, empty Org-wide CAPTCHA Settings are returned.

Request path parameters

N/A

Request query parameters

N/A

Request body

N/A

Response body

The requested Org-wide CAPTCHA Settings response

Use example

The following example returns Org-wide CAPTCHA Settings.

Request
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/org/captcha"
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "enabledPages": [
    "SSR",
    "SSPR",
    "SIGN_IN"
  ],
  "captchaId": "cap18c2Ey3iR9BLDb0g4",
  "_links": {
    "captcha": {
      "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
      "hints": {
        "allow": [
          "GET",
          "POST",
          "PUT",
          "DELETE"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/org/captcha",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

The following example returns empty Org-wide CAPTCHA Settings.

Request
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/org/captcha"
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "enabledPages": [],
  "captchaId": null,
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/org/captcha",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

Update Org-wide CAPTCHA Settings

PUT /api/v1/org/captcha

Updates Org-wide CAPTCHA Settings

Note: captchaId can't be null if enabledPages is null or empty.

Request path parameters

N/A

Request query parameters

N/A

Request body

The Org-wide CAPTCHA Settings to update

Response body

The updated Org-wide CAPTCHA Settings response

Use example

The following example enables CAPTCHA on self-service password recovery and sign-in pages by setting enabledPages with SSPR and SIGN_IN.

Request
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "captchaId": "cap18c2Ey3iR9BLDb0g4",
    "enabledPages": ["SSPR", "SIGN_IN"]
}' "https://${yourOktaDomain}/api/v1/org/captcha"
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "enabledPages": [
    "SSPR",
    "SIGN_IN"
  ],
  "captchaId": "cap18c2Ey3iR9BLDb0g4",
  "_links": {
    "captcha": {
      "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
      "hints": {
        "allow": [
          "GET",
          "POST",
          "PUT",
          "DELETE"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/org/captcha",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

The following example disables CAPTCHA org-wide by setting captchaId and enabledPages to null.

Request
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "captchaId": null,
    "enabledPages": null
}' "https://${yourOktaDomain}/api/v1/org/captcha"
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "enabledPages": [],
  "captchaId": null,
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/org/captcha",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

Error example

The following request returns an error when the updated captchaId is null but enabledPages isn't empty.

Request
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "captchaId": null,
    "enabledPages": ["SSR"]
}' "https://${yourOktaDomain}/api/v1/org/captcha"
Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: captchaId",
  "errorLink": "E0000001",
  "errorId": "oae-hk3rssXQmOWDRsaFfxe8A",
  "errorCauses": [
    {
      "errorSummary": "captchaId: Invalid CAPTCHA ID. The value of captchaId cannot be blank when enabledPages is not empty. Please resubmit with an existing CAPTCHA ID or disable CAPTCHA support on all supported pages."
    }
  ]
}

Delete Org-wide CAPTCHA Settings

DELETE /api/v1/org/captcha

Permanently deletes the Org-wide CAPTCHA Settings object

Request path parameters

N/A

Request query parameters

N/A

Request body

N/A

Response body

N/A

Use example

The following request deletes Org-wide CAPTCHA Settings.

Request
curl -v -X DELETE \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/org/captcha"
Response
HTTP/1.1 204 No Content
Content-Type: application/json

Org-wide CAPTCHA Settings API objects

Org-wide CAPTCHA Settings object

Org-wide CAPTCHA Settings properties

Property Type Description
captchaId String Unique key of the assigned CAPTCHA
enabledPages SSR, SSPR,SIGN_IN Array of pages that have CAPTCHA enabled

Available values for enabledPages:

CAPTCHA-enabled Page Description
SSR Self-service Registration
SSPR Self-service Password Recovery
SIGN_IN User sign-in page

Org-wide CAPTCHA Settings example

{
  "captchaId": "cap18c2Ey3iR9BLDb0g4",
  "enabledPages": ["SSPR", "SIGN_IN", "SSR"]
}

Org-wide CAPTCHA Settings Response object

Org-wide CAPTCHA Settings Response properties

Property Type Description
captchaId String Unique key of assigned CAPTCHA
enabledPages SSR, SSPR,SIGN_IN Array of pages that have CAPTCHA enabled
_links Links Link relations for this object

CAPTCHA example

{
    "enabledPages": [
        "SSPR"
    ],
    "captchaId": "cap18c2Ey3iR9BLDb0g4",
    "_links": {
        "captcha": {
            "href": "https://{yourOktaDomain}/api/v1/captchas/cap18c2Ey3iR9BLDb0g4",
            "hints": {
                "allow": [
                    "GET",
                    "POST",
                    "PUT",
                    "DELETE"
                ]
            }
        },
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/org/captcha",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        }
    }
}

Specifies link relations (see Web Linking (opens new window)) available for the current status of an application using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and lifecycle operations. The Links object is read-only.