CAPTCHAS API

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.

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

CAPTCHA operations

The CAPTCHAs API has the following CRUD operations:

Create CAPTCHA
Get CAPTCHA
Get all CAPTCHAs
Update CAPTCHA
Delete CAPTCHA

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

CAPTCHA Links object

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
Update Org-wide CAPTCHA Settings
Delete Org-wide CAPTCHA Settings

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

Org-wide CAPTCHA Links object

Edit This Page On GitHub

On this page

CAPTCHAS API

Get started

CAPTCHA operations

Create CAPTCHA

Request path parameters

Request query parameters

Request body

Response body

Use example

Request

Response

Error example

Request

Response

Get CAPTCHA

Request path parameters

Request query parameters

Request body

Response body

Use example

Request

Response

Get all CAPTCHAs

Request path parameters

Request query parameters

Request body

Response body

Use example

Request

Response

Update CAPTCHA

Request path parameters

Request query parameters

Request body

Response body

Use example

Response

Response

Delete CAPTCHA

Request path parameters

Request query parameters

Request body

Response body

Usage example

Request

Response

Error example

Request

Response

CAPTCHA API objects

CAPTCHA object

CAPTCHA properties

CAPTCHA example

CAPTCHA Response object

CAPTCHA Response properties

CAPTCHA example

CAPTCHA Links object

Org-wide CAPTCHA Settings operations

Get Org-wide CAPTCHA Settings

Request path parameters

Request query parameters

Request body

Response body

Use example

Request

Response

Request

Response

Update Org-wide CAPTCHA Settings

Request path parameters

Request query parameters

Request body

Response body

Use example

Request

Response

Request

Response

Error example