Notice that you must register at api.mucaptcha.com in order to use μcaptcha on your website.
Endpoints
The API has just two endpoints: one for requesting a μcaptcha challenge and other for verifying it.
GET https://api.mucaptcha.com/v1/challenge
Requests a μcaptcha challenge.
Parameters
| key (required) | Your public API key. |
Response
A JSON string with the following properties:
| image_id | Challenge image ID. |
| image_url | Challenge image URL. |
| image_width | Challenge image width. |
| image_height | Challenge image height. |
| error_code | A special code indicating any error that could have happened while requesting the challenge. If this property is set, the other properties will not. See the error codes section below for more info. |
POST https://api.mucaptcha.com/v1/verify
Verifies a μcaptcha challenge.
Parameters
| secret (required) | Your secret API key. |
| referer (required) | Your website URL. |
| challenge (required) | A valid μcaptcha challenge ID. |
| strokes (required) | A valid μcaptcha strokes. It must be a string representing a multidimensional array: [ [[x,y,t], ..., [x,y,t]], ..., [[x,y,t], ..., [x,y,t]] ] where [[x,y,t], ..., [x,y,t]] is a stroke, i.e., sequence of pen-down coordinates. |
| ip (optional) | The IP of the user requesting the challenge. |
Response
A JSON string with the following properties:
| success | Will be true if the challenge was successfully passed or false otherwise. |
| error_code | A special code indicating any error that could have happened while verifying the challenge. Will be empty if success is true. See the error codes section below for more info. |
Error codes
The following are possible values of the error_code property that you may receive either when requesting a challenge or when verifying it.
| missing-public-key | The public key parameter is missing. This parameter is required when requesting a challenge. |
| invalid-public-key | The public key parameter is invalid. You must follow the indications given when you registered for the API. |
| missing-secret-key | The secret parameter is missing. This parameter is required when verifying a challenge. |
| invalid-secret-key | The secret parameter is invalid. You must follow the indications given when you registered for the API. |
| missing-challenge | The challenge parameter is missing. This parameter is required when verifying a challenge. |
| invalid-challenge | The challenge parameter is invalid. You must verify a previously requested challenge. |
| missing-strokes | The strokes parameter is missing. This parameter is required when verifying a challenge. |
| invalid-strokes | The strokes parameter is invalid. It must be a well-formed JSON string representing a multidimensional coordinates array. |
| missing-referer | The referer parameter is missing. This parameter is required when verifying a challenge. |
| invalid-referer | The referer parameter is invalid. It must be the URL you entered when you registered your website. |
| referer-not-allowed | The referer is not allowed to verify the challenge. This is mostly due to a URL pointing to a non-registered website. |
| challenge-generation-error | There was an error while generating the challenge. This is usually a server-side error, not the user's fault. |
| challenge-verification-error | There was an error while verifying the challenge. This is usually a server-side error, not the user's fault. |
API clients
Currently there is only one official JavaScript implementation for including μcaptcha challenges on HTML pages:
https://api.mucaptcha.com/v1/js?key=YOUR_PUBLIC_KEY
The following are official server-side implementations of the μcaptcha API, namely for challenge verification.
- PHP 5.3 class (OOP style)
- PHP 5.3 function (procedural style)
API integration
There is a WordPress plugin to display μcaptcha on login and comment forms.