Iris Hosted

Let's Get started


to use iris captcha you need to first register a captcha for you domain, then tokens and Ids you need will be produces and you can use it.
add js file at the end of body exactly before it closes.

        <script src="{:CaptchaUniqID}" > </script>

Note : if you put it in the header it dose not work because header doesn't have access to body

then use <iris-captcha /> any where you want. for instance

...<form action="path/to/any" method="POST" >
        <input type="text" name="Name" ... />
        <iris-captcha name="irisCaptcha" />
        <button type="submit" value="Submit" > </button>

It's required by default.

if you want to check verification status you can call checkValidity() like this

        let captchaValidationStatus = document.getElementById("irisCaptcha").checkValidity() // true , false
        let captchaUserResponse = document.getElementById("irisCaptcha").value() // Response with Signature
        if( captchaValidationStatus ) {


  • name


  • onsuccess
  • onerror


  • checkValidity()
  • reportValidity()

Iris Hosted

Server Side

you have 2 option for user-Response verification,

  1. send the user-Response to Iris-Captcha Server and get the Response. ( old way )
  2. verify the user-Response's Signature Using Published Public-Key ( recommended and is much more fast )
It is best to combine the two, verify with the public key, if the signature was invalid, send the user response to the Iris-Captcha server and get the result, it is recommended to update the public key periodically
The Official Libraries are the best for use, they consist of both
send to Iris-Captcha Server

you should send a post request to whit the body of in the form of form Data.

        response string   // the User Response that you get it from the posted form - is a JWT
        secret   string   // your application Secret provided in your panel at
        remoteip string   // (Optional) the user Remote IP 

and the response will be a json like
        Code        int     // the Error Code 200 is OK / others shows Error
        Message     string  // error Message

        hostname    string  // the hostname of the site where the Iris-Captcha was solved
        success     bool    // true | false

Verify Signature with Published Key

the user response is JWT with Algorithm of RS256 with the payload of

            "success": true,            // the Captcha Solvation Status - true | false
            "hostname": "example.tld",  // the hostname of the site where the reCAPTCHA was solved ( your hostname )
            "ip": "",      // the user remote IP
            "exp": 1603318472,          // Expiration Time - Seconds Since Unix epoch 
            "iat": 1603318172           // Issued At - Seconds Since Unix epoch
for verification you need published Public-Key which is accessible throw
you can get also get and save to file with
curl >
or you can manually add as constant in your codes.
then you should parse JWT and validate Signature.

Iris-Captcha PHP Library


You can see and Download Iris-Captcha from GitHub Releases. Simply include "path/to/irisCaptchaLib.php" and use it.

Example Of Using Library with Public-Key that offer Best Effort

Example Of Using Library with Requesting to Iris-Captcha Server


Iris-Captcha with Golang

Library : work in progress
Example of Using Public-Key ( Pure Go )

                            Example of Requesting to Iris-Captcha Server ( Pure Go )


Self Hosting Captcha

You Can Simply Install Iris Captcha in your server. we have an Installer for it.

for installation instruction follow up the usage tab of your service panel at .

Choosing Right Image

the difficulty of your captcha extremely depend on your pictures, choosing simple Image may causes to be solvable for robots .
the picture you choosing shouldn't contains overall corrected lines. take a look at this pictures.

they are solvable for robots because most of the lines and edges in the image shows corrected orientation.
read more at here

in the other hand the images that contain many noises and lines that are meaningful for humans makes the captcha to be harder for bots and easy for humans.
take a look at this pictures.

register to newsletter subscription if you are interested in similar blogs. we are going to get deep

if you are interested in contributing examples in other languages , check out our github account.