Private Captcha

https://docs.privatecaptcha.com/docs
Admin
Private Captcha is a privacy-focused CAPTCHA solution that provides bot protection with integrations...
Tokens:36,296
Snippets:323
Trust Score:6.5
Update:9 months ago
Show doc for...
Tokens:
Raw
### Clone Self-Hosting Repository (Bash)

Source: https://docs.privatecaptcha.com/docs/deployment/quickstart

This snippet clones the Private Captcha self-hosting repository, which contains a Docker-based quickstart template. It's the first step in setting up the application.

```bash
git clone https://github.com/PrivateCaptcha/self-hosting.git private-captcha
cd private-captcha
```

--------------------------------

### Create and Edit .env File (Shell)

Source: https://docs.privatecaptcha.com/docs/deployment/quickstart

This command copies the example environment file to .env and opens it for editing. This file is crucial for configuring Private Captcha with your specific settings, such as domain names and email credentials.

```shell
cp .env.example .env
$EDITOR .env
```

--------------------------------

### Run Docker Compose Stack (Shell)

Source: https://docs.privatecaptcha.com/docs/deployment/quickstart

This command starts the Private Captcha application using Docker Compose. It builds and runs all the necessary services defined in the Docker Compose configuration.

```shell
docker compose up
```

--------------------------------

### Configure Localhost Hosts File (Shell)

Source: https://docs.privatecaptcha.com/docs/deployment/quickstart

These commands add entries to the /etc/hosts file to map local domain names to localhost. This is necessary for local-only development setups of Private Captcha, ensuring subdomains resolve correctly.

```shell
127.0.0.1       portal.privatecaptcha.local
127.0.0.1       api.privatecaptcha.local
127.0.0.1       cdn.privatecaptcha.local
```

--------------------------------

### HTML: Complete Invisible Captcha Example

Source: https://docs.privatecaptcha.com/docs/tutorials/invisible-captcha

A comprehensive HTML example illustrating the setup of an invisible CAPTCHA. It includes hiding the widget, setting callbacks, and configuring the start mode to 'click' for manual triggering via the 'execute()' API method.

```html
<form>
    <div class="private-captcha"
        data-sitekey="xyz"
        data-display-mode="hidden"
        data-start-mode="click"
        data-started-callback="invisibleCaptchaStarted"
        data-finished-callback="invisibleCaptchaFinished">
    </div>
    <button type="button" onclick="window.privateCaptcha.autoWidget.execute()">
        <svg id="spinner" ... />
        <svg id="checkmark" ... />

        Submit
    </button>
</form>
```

--------------------------------

### Install Private Captcha Go SDK

Source: https://docs.privatecaptcha.com/docs/integrations/go

This command installs the Private Captcha Go SDK. It is required before you can use the SDK in your Go project.

```go
go get -u github.com/PrivateCaptcha/private-captcha-go
```

--------------------------------

### Install Private Captcha PHP SDK using Composer

Source: https://docs.privatecaptcha.com/docs/integrations/php

This command installs the Private Captcha PHP SDK using Composer, the dependency manager for PHP. Ensure you have Composer installed before running this command.

```bash
composer require private-captcha/private-captcha-php
```

--------------------------------

### Install Private Captcha SDK using pip

Source: https://docs.privatecaptcha.com/docs/integrations/python

This command installs the Private Captcha Python SDK. Ensure you have pip installed and accessible in your environment.

```bash
pip install private-captcha
```

--------------------------------

### HTML: Setup Captcha Callbacks

Source: https://docs.privatecaptcha.com/docs/tutorials/invisible-captcha

This HTML snippet shows how to configure the necessary callbacks for the invisible CAPTCHA. 'data-started-callback' and 'data-finished-callback' are mandatory when using the invisible mode to handle CAPTCHA start and completion events.

```html
<div class="private-captcha" data-sitekey="xyz"
	...
    data-started-callback="invisibleCaptchaStarted"
    data-finished-callback="invisibleCaptchaFinished"
    ...
>
</div>
```

--------------------------------

### POST /verify

Source: https://docs.privatecaptcha.com/docs/tutorials/complete-example

Verifies a captcha solution by sending the solution token to the PrivateCAPTCHA API.

```APIDOC
## POST /verify

### Description
This endpoint is used to verify the captcha solution provided by the user. It is called after the captcha widget has finished solving the puzzle, and the solution is typically submitted as a hidden form field.

### Method
POST

### Endpoint
`https://api.privatecaptcha.com/verify`

### Parameters
#### Headers
- **X-Api-Key** (string) - Required - Your PrivateCAPTCHA API key.

#### Request Body
- **solution** (string) - Required - The captcha solution token obtained from the hidden form field (e.g., `private-captcha-solution`).

### Request Example
```
POST https://api.privatecaptcha.com/verify
Host: api.privatecaptcha.com
X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

private-captcha-solution=AAAAAAACAhQEAOiDAAAAAAC...IsoSTgYAAA=
```

### Response
#### Success Response (200)
- **success** (boolean) - True if the solution is valid, false otherwise.
- **code** (integer) - 0 if the solution is valid. Other codes indicate specific errors.
- **timestamp** (string) - The time the verification was processed.
- **origin** (string) - The origin of the request.

#### Response Example
```json
{
  "success": true,
  "code": 0,
  "timestamp": "2025-01-14T11:19:34Z",
  "origin": "27ca-193-138-7-216.ngrok-free.app"
}
```

#### Error Response (Non-200 Status Codes)
Details will vary based on the error, but typically indicate issues like invalid API key, malformed request, or invalid solution.

### Troubleshooting
- Ensure the `X-Api-Key` header is correctly set with your valid API key.
- The request body should contain the `private-captcha-solution` value.
- If verification fails (red page), check console logs for errors and ensure your domain is allowed in the property settings.
```

--------------------------------

### Configure Docker Compose Override (YAML)

Source: https://docs.privatecaptcha.com/docs/deployment/quickstart

This YAML snippet defines a Docker Compose override file to expose the Private Captcha service's ports directly. This is an optional step for production environments, typically used instead of a reverse proxy.

```yaml
services:
  privatecaptcha:
    ports:
      - 8080:8080
```

--------------------------------

### Install React SDK

Source: https://docs.privatecaptcha.com/docs/integrations/react

Installs the Private Captcha React SDK using npm. This package provides a React component for easy integration into your application.

```bash
npm install @private-captcha/private-captcha-react
```

--------------------------------

### Create Basic Go Web Server

Source: https://docs.privatecaptcha.com/docs/tutorials/complete-example

This Go program sets up a simple HTTP server that serves the 'index.html' file for the root path ('/'). It listens on port 8081 and logs any fatal errors. It returns a 404 for any other paths.

```go
package main

import (
	"log"
	"net/http"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if r.URL.Path == "/" {
			http.ServeFile(w, r, "index.html")
			return
		}
		// Return 404 for any other paths
		http.NotFound(w, r)
	})

	if err := http.ListenAndServe(":8081", nil); err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Install Private Captcha .NET Package

Source: https://docs.privatecaptcha.com/docs/integrations/dotnet

Installs the Private Captcha SDK package using the .NET CLI or the Package Manager Console. This is the first step to using the server-side verification features in your .NET application.

```csharp
dotnet add package PrivateCaptcha
```

```csharp
Install-Package PrivateCaptcha
```

--------------------------------

### Install Private Captcha Javascript SDK

Source: https://docs.privatecaptcha.com/docs/integrations/javascript

Installs the private-captcha-js package using npm. This is the first step to integrating Private Captcha verification into your Javascript backend.

```bash
npm install private-captcha-js
```

--------------------------------

### Install Private Captcha Ruby Gem

Source: https://docs.privatecaptcha.com/docs/integrations/ruby

Instructions for adding the private_captcha gem to your Ruby application's Gemfile and installing it using bundler, or installing it directly using the gem install command.

```ruby
gem 'private_captcha'
```

```bash
bundle install
```

```bash
gem install private_captcha
```

--------------------------------

### Popup Display Mode with Click Start (HTML)

Source: https://docs.privatecaptcha.com/docs/reference/widget-options

Configures the captcha widget to display in a popup relative to a 'private-captcha-anchor' parent. It uses 'click' mode for starting the captcha and requires a site key. This setup is recommended for security purposes.

```html
<form>
    <div class="private-captcha-anchor">
        <div class="private-captcha" data-sitekey="xyz"
             data-display-mode="popup" data-start-mode="click"></div>
    </div>
    <!-- ... -->
    <button type="button" onclick="window.privateCaptcha.autoWidget.execute()">Click me!</button>
</form>
```

--------------------------------

### Configure Retry and Backoff Options for Captcha Verification in Go

Source: https://docs.privatecaptcha.com/docs/integrations/go

This example shows how to configure retry and backoff options when verifying puzzle solutions. You can set the maximum backoff seconds and the number of attempts.

```go
input := pc.Configuration{
	Solution: "solution",
	MaxBackoffSeconds: 10,
	Attempts: 10,
}
output, err := client.Verify(ctx, input)
// ... handle err
```

--------------------------------

### Verify Captcha Solution with Go

Source: https://docs.privatecaptcha.com/docs/tutorials/complete-example

This Go function demonstrates how to verify a captcha solution by sending a POST request to the Private Captcha API's `/verify` endpoint. It requires the captcha solution string and an API key. The function returns an error if the verification fails.

```go
import (
    "encoding/json"
    "errors"
    "fmt"
    "log"
    "net/http"
    "strings"
)

func checkSolution(solution, apiKey string) error {
	req, err := http.NewRequest("POST", "https://api.privatecaptcha.com/verify", strings.NewReader(solution))
	if err != nil {
		return err
	}

	req.Header.Set("X-Api-Key", apiKey)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	response := struct {
		Success bool `json:"success"`
        Code    int  `json:"code"`
		// NOTE: other fields omitted for brevity
	}{}

	if err := json.NewDecoder(resp.Body).Decode(&response); err != nil {
		return err
	}

	if !(response.Success && response.Code == 0) {
		return errors.New("solution is not correct")
	}

	return nil
}

func main() {
	http.HandleFunc("POST /submit", func(w http.ResponseWriter, r *http.Request) {
        const page = `<!DOCTYPE html><html><body style="background-color: %s;"></body></html>`
		captchaSolution := r.FormValue("private-captcha-solution")
		if err := checkSolution(captchaSolution, "your-api-key"); err != nil {
			fmt.Fprintf(w, page, "red")
			return
		}
		fmt.Fprintf(w, page, "green")
	})
    // ....
}
```

--------------------------------

### Quick start: Verify captcha solution in Python

Source: https://docs.privatecaptcha.com/docs/integrations/python

This Python snippet demonstrates how to initialize the Private Captcha client with an API key and verify a user-provided captcha solution. It includes basic error handling for verification failures.

```python
from private_captcha import Client

# Initialize the client with your API key
client = Client(api_key="your-api-key-here")

# Verify a captcha solution
try:
    result = client.verify(solution="user-solution-from-frontend")
    if result.ok():
        print("Captcha verified successfully!")
    else:
        print(f"Verification failed: {result}")
except Exception as e:
    print(f"Error: {e}")
```

--------------------------------

### Expose Local Server Publicly with Ngrok

Source: https://docs.privatecaptcha.com/docs/tutorials/complete-example

This command uses ngrok to expose a local server running on port 8081 to the public internet. It provides a temporary public URL that can be used for testing. This is useful for making a local development environment accessible for external services.

```bash
# run ngrok to our previously exposed port 8081
ngrok http 8081
```

--------------------------------

### GET /org/{org_id}/property/{property_id}

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Retrieves detailed settings for a specific property.

```APIDOC
## GET /org/{org_id}/property/{property_id}

### Description
Retrieves detailed settings for a specific property.

### Method
GET

### Endpoint
/org/{org_id}/property/{property_id}

### Parameters
#### Path Parameters
- **org_id** (string) - Required - The ID of the organization.
- **property_id** (string) - Required - The ID of the property.

#### Query Parameters
None

#### Request Body
None

### Request Example
```
curl -X GET https://api.privatecaptcha.com/org/vDWtASYqrB/property/0VgGggmbGa \
  -H "X-API-Key: your-portal-api-key"
```

### Response
#### Success Response (200)
- **meta** (object) - Object containing metadata about the request.
  - **code** (integer) - Response status code.
  - **description** (string) - Description of the status code.
  - **request_id** (string) - Unique identifier for the request.
- **data** (object) - Object containing property details.
  - **id** (string) - Unique identifier of the property.
  - **name** (string) - Display name of the property.
  - **domain** (string) - The domain name where the widget is deployed.
  - **sitekey** (string) - The public key used to integrate the widget.
  - **level** (integer) - Difficulty level of the puzzle. Must be between 1 and 255.
  - **growth** (string) - Difficulty growth rate. Allowed values: `constant`, `slow`, `medium`, `fast`.
  - **validity_seconds** (integer) - Duration in seconds for which a single solution remains valid.
  - **allow_subdomains** (boolean) - If `true`, the widget will work on subdomains of the specified domain.
  - **allow_localhost** (boolean) - If `true`, the widget will work on `localhost` and `127.0.0.1`.
  - **max_replay_count** (integer) - Maximum number of times a single solution can be verified during the `validity_seconds`. Must be between `1` and `1,000,000`.

#### Response Example
```json
{
  "meta": { "code": 1000, "description": "OK", "request_id": "qwerty123" },
  "data": {
    "id": "0VgGggmbGa",
    "name": "Primary Domain",
    "domain": "example.com",
    "sitekey": "525e0ef5b9bc489f882274b3ca24b710",
    "level": 1,
    "growth": "medium",
    "validity_seconds": 21600,
    "allow_subdomains": false,
    "allow_localhost": false,
    "max_replay_count": 1
  }
}
```
```

--------------------------------

### Example of Verify Response JSON

Source: https://docs.privatecaptcha.com/docs/tutorials/complete-example

This JSON structure represents a successful verification response from the Private Captcha API. It includes a success flag, a code indicating the status, a timestamp, and the origin of the request.

```json
{"success":true,"code":0,"timestamp":"2025-01-14T11:19:34Z","origin":"27ca-193-138-7-216.ngrok-free.app"}
```

--------------------------------

### Quick Start: Verify Captcha Solution in PHP

Source: https://docs.privatecaptcha.com/docs/integrations/php

This PHP code snippet demonstrates the basic usage of the Private Captcha PHP SDK. It initializes a client with an API key and verifies a user-provided captcha solution, handling success and failure cases.

```php
<?php

use PrivateCaptcha\Client;

// Initialize the client with your API key
$client = new Client(apiKey: "your-api-key-here");

// Verify a captcha solution
try {
    $result = $client->verify(solution: "user-solution-from-frontend");
    if ($result->isOK()) {
        echo "Captcha verified successfully!";
    } else {
        echo "Verification failed: {$result}";
    }
} catch (Exception $e) {
    echo "Error: {$e->getMessage()}";
}

```

--------------------------------

### Running Manual Database Migrations

Source: https://docs.privatecaptcha.com/docs/deployment/production

Command to manually run database migrations for larger, custom installations of Private Captcha. It pipes environment variables from a secrets file and specifies the migration mode and target version.

```bash
cat secrets.env | bin/server -mode migrate -migrate-hash=$(git rev-list -1 HEAD) -env stdin
```

--------------------------------

### Create Basic HTML Form

Source: https://docs.privatecaptcha.com/docs/tutorials/complete-example

This snippet defines a simple HTML form with an email input field and a submit button. It includes basic styling to center the form on the page. The submit button is initially disabled.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Private Captcha Example</title>
    <style>
        body {
            display:flex; 
            flex-direction: column; 
            min-height: 100vh;
        }

        form {
            max-width: 32rem; 
            margin: auto; 
            display: flex; 
            flex-direction: column; 
            gap: 20px; 
            border: 1px #ccc solid;
            padding: 20px;
        }
    </style>
</head>
<body>
    <div style="display: flex; flex: 1 1 0%">
        <form action='/submit' method="POST">
            <label> Email: </label>
            <input type="email" name="email" placeholder="Email address" required />
            <button id="formSubmit" type="submit" disabled> Submit </button>
        </form>
    </div>
</body>
</html>
```

--------------------------------

### Integrate Captcha Widget with Callback (HTML)

Source: https://docs.privatecaptcha.com/docs/tutorials/complete-example

This HTML snippet demonstrates how to integrate the PrivateCaptcha widget into a form. It includes the necessary `data-sitekey` and crucially, the `data-finished-callback` attribute, which links the widget's completion event to the `onCaptchaSolved` JavaScript function.

```html
<div class="private-captcha" data-sitekey="xyz"
    data-finished-callback="onCaptchaSolved"></div>
```

--------------------------------

### Configure Retry Behavior for Captcha Verification (Ruby)

Source: https://docs.privatecaptcha.com/docs/integrations/ruby

Example demonstrating how to configure retry attempts and maximum backoff seconds directly within the `verify` method call for Private Captcha verification.

```ruby
result = client.verify(
  'solution',
  max_backoff_seconds: 15,  # maximum wait between retries
  attempts: 3               # number of retry attempts
)
```

--------------------------------

### Configure ASP.NET Core for Private Captcha Middleware

Source: https://docs.privatecaptcha.com/docs/integrations/dotnet

Shows how to register the `PrivateCaptchaClient` for dependency injection in an ASP.NET Core application. This setup is required before applying the `UsePrivateCaptcha` middleware to protect endpoints.

```csharp
// Program.cs
using PrivateCaptcha;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
{
    var config = new PrivateCaptchaConfiguration { ApiKey = "YOUR_API_KEY" };
    return new PrivateCaptchaClient(config);
});

// ... other services
```

--------------------------------

### Configure retry options for Private Captcha verification

Source: https://docs.privatecaptcha.com/docs/integrations/python

This example shows how to configure retry attempts and backoff strategies when verifying puzzle solutions with the Private Captcha client. This can be useful for handling transient network issues.

```python
result = client.verify(
    max_backoff_seconds=15,  # maximum wait between retries
    attempts=3               # number of retry attempts
)
```

--------------------------------

### Configure Private Captcha Rack Middleware (Ruby)

Source: https://docs.privatecaptcha.com/docs/integrations/ruby

Example of using Private Captcha as Rack middleware to protect your application. It shows how to configure the API key and the HTTP status code to return on failed verification.

```ruby
require 'private_captcha'

use PrivateCaptcha::Middleware,
  api_key: 'your-api-key',
  failed_status_code: 403
```

--------------------------------

### Get Captcha Solution using solution()

Source: https://docs.privatecaptcha.com/docs/reference/captcha-object

The `solution()` method retrieves the found captcha solution. It can be used within callbacks for custom processing of form data. This function is typically called on the widget object passed as a parameter to the callback.

```javascript
function onCaptchaSolved(widget) {
    console.log('Found solution:', widget.solution());
}
```

--------------------------------

### Import and Instantiate Private Captcha Client

Source: https://docs.privatecaptcha.com/docs/integrations/go

This code snippet shows how to import the Private Captcha SDK and create a new client instance. You need an API key to instantiate the client. The Configuration object allows for advanced settings like switching to the EU endpoint.

```go
import pc "github.com/PrivateCaptcha/private-captcha-go"

// ...

client, err := pc.NewClient(pc.Configuration{APIKey: "pc_abcdef"})
// ... handle err
```

--------------------------------

### Initialize Private Captcha Client and Verify Solution (Ruby)

Source: https://docs.privatecaptcha.com/docs/integrations/ruby

Demonstrates how to initialize the Private Captcha client with an API key and verify a user-provided captcha solution. It includes error handling for verification failures.

```ruby
require 'private_captcha'

# Initialize the client with your API key
client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key-here'
end

# Verify a captcha solution
begin
  result = client.verify('user-solution-from-frontend')
  if result.ok?
    puts 'Captcha verified successfully!'
  else
    puts "Verification failed: #{result.error_message}"
  end
rescue PrivateCaptcha::Error => e
  puts "Error: #{e.message}"
end
```

--------------------------------

### Update API Key with WP-CLI

Source: https://docs.privatecaptcha.com/docs/integrations/wordpress

This WP-CLI command allows you to update the Private Captcha API key for your WordPress installation. This is useful for emergency key rotations or when the existing key expires. Ensure you have WP-CLI installed and configured for your WordPress site.

```bash
wp private-captcha update-api-key "your-new-api-key"
```

--------------------------------

### Verify Captcha Solution Directly in Go

Source: https://docs.privatecaptcha.com/docs/integrations/go

This method directly verifies a captcha solution against the Private Captcha API. It supports automatic backoff and retrying, which can be configured via the VerifyInput parameter. The output object contains the verification status and any potential errors.

```go
output, err := client.Verify(ctx, pc.VerifyInput{Solution: solution})
// ... handle err

if !output.OK() {
	fmt.Printf("Captcha verification failed. Error: %s", result.Error())
}
```

--------------------------------

### GET /orgs

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Retrieves a list of all organizations owned by the authenticated user.

```APIDOC
## GET /orgs

### Description
Retrieves a list of all organizations owned by the authenticated user.

### Method
GET

### Endpoint
`/orgs`

### Output
Array of objects containing `id` (string) and `name` (string).

### Request Example
```curl
curl -X GET https://api.privatecaptcha.com/orgs \
  -H "X-API-Key: your-portal-api-key"
```

### Response Example
```json
{
  "meta": {
    "code": 1000,
    "description": "OK",
    "request_id": "req_12345"
  },
  "data": [
    {
      "id": "vDWtASYqrB",
      "name": "Company Website"
    },
    ...
  ]
}
```
```

--------------------------------

### GET /asynctask/{id}

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Retrieves the current status and results of an asynchronous task using its ID.

```APIDOC
## GET /asynctask/{id}

### Description
Retrieves the current status and results of an asynchronous task. You can use this endpoint to check if a previously initiated operation (like deleting properties) has completed and to fetch its results.

### Method
GET

### Endpoint
/asynctask/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the asynchronous task.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://api.privatecaptcha.com/asynctask/e3e6854e06944cf48f49f93abb5a527e \
  -H "X-API-Key: your-portal-api-key"
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the asynchronous task.
- **finished** (boolean) - Indicates whether the task has completed.
- **result** (array) - An array containing the results of the operation. The structure of each element in the array depends on the specific operation that was performed.

#### Response Example
```json
{
  "meta": {
    "code": 1000,
    "description": "OK",
    "request_id": "qwerty123"
  },
  "data": {
    "id": "e3e6854e06944cf48f49f93abb5a527e",
    "finished": true,
    "result": [
      { "code": 1000 },
      ...
    ]
  }
}
```
```

--------------------------------

### GET /org/{org_id}/properties

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Lists properties associated with a specific organization. This endpoint supports pagination.

```APIDOC
## GET /org/{org_id}/properties

### Description
Lists properties associated with a specific organization. This endpoint supports pagination.

### Method
GET

### Endpoint
/org/{org_id}/properties

### Parameters
#### Path Parameters
- **org_id** (string) - Required - The ID of the organization.

#### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **per_page** (integer) - Optional - The number of items per page (max 50).

#### Request Body
None

### Request Example
```
curl -X GET "https://api.privatecaptcha.com/org/vDWtASYqrB/properties?page=1&per_page=10"
  -H "X-API-Key: your-portal-api-key"
```

### Response
#### Success Response (200)
- **meta** (object) - Object containing metadata about the request.
  - **code** (integer) - Response status code.
  - **description** (string) - Description of the status code.
  - **request_id** (string) - Unique identifier for the request.
- **data** (object) - Object containing the properties and pagination information.
  - **properties** (array) - Array of property objects.
    - **id** (string) - Unique identifier of the property.
    - **name** (string) - Display name of the property.
    - **sitekey** (string) - The public key used to integrate the widget.
  - **pagination** (object) - Pagination details.
    - **page** (integer) - Current page number.
    - **per_page** (integer) - Items per page.
    - **has_more** (boolean) - Indicates if there are more pages.

#### Response Example
```json
{
  "meta": { "code": 1000, "description": "OK", "request_id": "qwerty123" },
  "data": {
    "properties": [
      {
        "id": "0VgGggmbGa",
        "name": "Primary Domain",
        "sitekey": "525e0ef5b9bc489f882274b3ca24b710"
      },
      ...
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "has_more": false
    }
  }
}
```
```

--------------------------------

### Testing with Predefined Sitekey

Source: https://docs.privatecaptcha.com/docs/reference/testing

Use a dummy sitekey for development and testing purposes. This sitekey does not incur costs and always passes verification, although the captcha widget still needs interaction.

```APIDOC
## Client-side Testing with Predefined Sitekey

### Description
This example shows how to integrate the Private Captcha widget for testing using a predefined dummy sitekey.

### Method
Not applicable (Client-side HTML integration)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```html
<div class="private-captcha" data-sitekey="aaaaaaaabbbbccccddddeeeeeeeeeeee">
</div>
```

### Response
#### Success Response (Widget Interaction)

When the widget is clicked, it will display red "testing" text, indicating it's not for production use.

#### Response Example
(Visual indication on the widget: red "testing" text)
```

```APIDOC
## Server-side Verification with Predefined Sitekey

### Description
This section details how to verify captcha responses on the server-side when using the dummy sitekey. Responses will always indicate success but may include specific error codes for testing.

### Method
POST

### Endpoint
`https://api.privatecaptcha.com/verify`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **payload** (string) - Required - The captcha verification payload.
- **X-Api-Key** (string) - Required - Your API key.

### Request Example
```bash
curl \
  -X POST \
  -H "X-Api-Key: your-api-key" \
  -d "AQIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.Aaqqqqq7u8zM3d3u7u7u7u4AAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAA=.AQCBnM2czBK6rlq+l06lXBtIDQH/PFk=" \
  https://api.privatecaptcha.com/verify
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the verification passed (will be true for test sitekeys).
- **code** (integer) - A code representing the verification result (e.g., 10 for 'property-test').
- **timestamp** (string) - The timestamp of the verification.
- **origin** (string) - The origin of the verification.

#### Response Example
```json
{
  "success": true,
  "code": 10,
  "timestamp": "0001-01-01T00:00:00Z",
  "origin": ""
}
```

**Note**: Code `10` corresponds to the `"property-test"` error description.
```

--------------------------------

### Successful Verification Response

Source: https://docs.privatecaptcha.com/docs/reference/verify-api

Example of a successful response from the /verify API endpoint. It indicates that the captcha solution is valid and provides a timestamp and origin.

```json
{
  "success": true,
  "timestamp": "2025-01-13T16:17:27+00:00",
  "origin": "privatecaptcha.com",
  "code": 0
}
```

--------------------------------

### Get User Organizations (API)

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Retrieves a list of all organizations owned by the authenticated user. The response includes an array of organization objects, each with an 'id' and 'name'.

```HTTP
curl -X GET https://api.privatecaptcha.com/orgs \
  -H "X-API-Key: your-portal-api-key"
```

```JSON
{
  "meta": {
    "code": 1000,
    "description": "OK",
    "request_id": "req_12345"
  },
  "data": [
    {
      "id": "vDWtASYqrB",
      "name": "Company Website"
    },
    ...
  ]
}
```

--------------------------------

### POST /org

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Creates a new organization for the user. Note that the `id` field in the input must be empty.

```APIDOC
## POST /org

### Description
Creates a new organization for the user. Note that the `id` field in the input must be empty.

### Method
POST

### Endpoint
`/org`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new organization.

### Request Example
```curl
curl -X POST https://api.privatecaptcha.com/org \
  -H "X-API-Key: your-portal-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Marketing Org"}'
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created organization's `id` (string) and `name` (string).

#### Response Example
```json
{
  "meta": {
    "code": 1000,
    "description": "OK",
    "request_id": "req_12345"
  },
  "data": {
    "id": "vDWtASYqrB",
    "name": "New Marketing Org"
  }
}
```
```

--------------------------------

### HTML Form with Captcha Solution

Source: https://docs.privatecaptcha.com/docs/reference/verify-api

An example of an HTML form containing a hidden input field that stores the captcha solution after the puzzle is solved. This field is crucial for server-side validation.

```html
<form>
    <!-- ... -->
    <input name="private-captcha-solution" type="hidden" value="AAAAAAACAhQEAOiDAAAAAAC...IsoSTgYAAA=">
    <!-- ... -->
</form>
```

--------------------------------

### Server-Side Verification with Dummy Sitekey

Source: https://docs.privatecaptcha.com/docs/reference/testing

Simulate a server-side verification request using `curl` with a dummy sitekey. The API response for a test property will always indicate success, along with a 'property-test' error code.

```bash
curl \
  -X POST \
  -H "X-Api-Key: your-api-key" \
  -d "AQIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.Aaqqqqq7u8zM3d3u7u7u7u4AAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAA=.AQCBnM2czBK6rlq+l06lXBtIDQH/PFk=" \
  https://api.privatecaptcha.com/verify
```

```json
{"success":true,"code":10,"timestamp":"0001-01-01T00:00:00Z","origin":""}
```

--------------------------------

### Integrate Private Captcha verification with Django

Source: https://docs.privatecaptcha.com/docs/integrations/python

This Django example demonstrates how to verify a captcha solution from POST data. It utilizes the `verify_request` method and catches `SolutionError` for failed verifications.

```python
from django.http import HttpResponse
from private_captcha import Client, SolutionError

client = Client(api_key="your-api-key")

def submit_view(request):
    if request.method == 'POST':
        try:
            client.verify_request(request.POST)
            # Process form data
            return HttpResponse("Success!")
        except SolutionError:
            return HttpResponse("Captcha failed", status=400)
```

--------------------------------

### Get Async Task Details (curl)

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Retrieves the current status and results of an asynchronous task using its ID. The output includes whether the task is finished and its results.

```curl
curl -X GET https://api.privatecaptcha.com/asynctask/e3e6854e06944cf48f49f93abb5a527e \
  -H "X-API-Key: your-portal-api-key"
```

--------------------------------

### Use Private Captcha with EU or custom domains

Source: https://docs.privatecaptcha.com/docs/integrations/python

This example demonstrates configuring the Private Captcha client to use the EU-specific domain for data isolation or a custom domain for self-hosted instances.

```python
from private_captcha import Client, EU_DOMAIN

# Use EU domain
eu_client = Client(
    api_key="your-api-key",
    domain=EU_DOMAIN  # api.eu.privatecaptcha.com
)

# Or specify custom domain in case of self-hosting
custom_client = Client(
    api_key="your-api-key", 
    domain="your-custom-domain.com"
)
```

--------------------------------

### Integrate Private Captcha verification with Flask

Source: https://docs.privatecaptcha.com/docs/integrations/python

This Flask example shows how to verify a captcha solution submitted via a form. It uses the `verify_request` method and handles `SolutionError` for verification failures.

```python
from flask import Flask, request
from private_captcha import Client, SolutionError

app = Flask(__name__)
client = Client(api_key="your-api-key")

@app.route('/submit', methods=['POST'])
def submit_form():
    try:
        # Verify captcha from form data
        client.verify_request(request.form)

        # Process your form data here
        return "Form submitted successfully!"

    except SolutionError:
        return "Captcha verification failed", 400
```

--------------------------------

### Simple HTTP Middleware for Captcha Verification in Go

Source: https://docs.privatecaptcha.com/docs/integrations/go

This is a basic HTTP middleware that checks captcha verification. If the solution is not verified, it returns an http.StatusForbidden. The client's Configuration object can be used to customize the status code returned.

```go
mux.Handle("POST /my/form", client.VerifyFunc(actualHandler))
```

--------------------------------

### Basic Captcha Verification in .NET

Source: https://docs.privatecaptcha.com/docs/integrations/dotnet

Demonstrates how to perform a basic server-side CAPTCHA verification using the Private Captcha SDK. It involves creating a configuration with an API key, instantiating the `PrivateCaptchaClient`, and calling the `VerifyAsync` method with the CAPTCHA solution.

```csharp
var config = new PrivateCaptchaConfiguration
{
    ApiKey = "YOUR_API_KEY"
};
var captchaClient = new PrivateCaptchaClient(config);

var result = await captchaClient.VerifyAsync(new VerifyInput { Solution = captchaSolution });
if (result.OK())
{
    Console.WriteLine("Captcha verification succeeded!");
}
else
{
    // Verification failed, you can check the reason.
    Console.WriteLine($"Verification failed: {result.GetErrorMessage()}");
}
```

--------------------------------

### Verify Captcha Solution Using HTTP Request in Go

Source: https://docs.privatecaptcha.com/docs/integrations/go

This function operates at the http.Request level, extracting and verifying the captcha solution from a form field. The form field is configured via the client's Configuration object. If verification fails, an error is returned.

```go
func handler(w http.ResponseWriter, r *http.Request) {
	if err := client.VerifyRequest(r.Context(), r); err != nil {
		return
	}
}
```

--------------------------------

### Create Organization (API)

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Creates a new organization for the user. The input requires a JSON object with a 'name' field. The 'id' field in the input must be empty. The output includes the created organization's 'id' and 'name'.

```HTTP
curl -X POST https://api.privatecaptcha.com/org \
  -H "X-API-Key: your-portal-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Marketing Org"}'
```

```JSON
{
  "meta": {
    "code": 1000,
    "description": "OK",
    "request_id": "req_12345"
  },
  "data": {
    "id": "vDWtASYqrB",
    "name": "New Marketing Org"
  }
}
```

--------------------------------

### Get Property Details - cURL

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Retrieves detailed settings for a specific property within an organization. Requires both the organization ID and the property ID. The output is a single object with comprehensive property configuration.

```curl
curl -X GET https://api.privatecaptcha.com/org/vDWtASYqrB/property/0VgGggmbGa \
  -H "X-API-Key: your-portal-api-key"
```

--------------------------------

### Client-Side Testing with Dummy Sitekey

Source: https://docs.privatecaptcha.com/docs/reference/testing

Embed a Private Captcha widget for testing using a predefined dummy sitekey. This sitekey ensures that verification always passes without incurring actual costs. The widget will display 'testing' text when clicked.

```html
<div class="private-captcha" data-sitekey="aaaaaaaabbbbccccddddeeeeeeeeeeee">
</div>
```

--------------------------------

### Testing with Localhost Access

Source: https://docs.privatecaptcha.com/docs/reference/testing

Instructions on how to enable localhost access for the Private Captcha widget to function on your local development environment. This is not needed when using the dummy sitekey.

```APIDOC
## Testing with Localhost Access

### Description
To load the Private Captcha widget on the `localhost` domain, you must explicitly allow it in the settings of your Private Captcha property. This is a CORS policy requirement and is not necessary if you are using the dummy sitekey.

### Method
Configuration setting (Portal)

### Endpoint
Not applicable (Configuration within the Private Captcha portal)

### Parameters
None

### Request Example
Access the Private Captcha portal, navigate to the settings for your property, and add `localhost` to the allowed domains.

### Response
No direct API response. Successful configuration allows the widget to load on localhost.
```

--------------------------------

### Integrate Private Captcha Verification in Rails Controller (Ruby)

Source: https://docs.privatecaptcha.com/docs/integrations/ruby

Provides an example of integrating Private Captcha verification within a Rails controller action. It initializes the client, verifies the request, and handles success or failure responses.

```ruby
class FormsController < ApplicationController
  def submit
    client = PrivateCaptcha::Client.new do |config|
      config.api_key = 'your-api-key'
    end

    begin
      client.verify_request(request)
      # Process form data
      render plain: 'Success!'
    rescue PrivateCaptcha::Error
      render plain: 'Captcha failed', status: :bad_request
    end
  end
end
```

--------------------------------

### Verify Captcha Solution with Javascript

Source: https://docs.privatecaptcha.com/docs/integrations/javascript

Demonstrates basic captcha verification using the `private-captcha-js` SDK. It creates a client instance with an API key and calls the `verify` method with the captcha solution. The `result.ok()` method checks if the verification was successful.

```javascript
import { createClient } from 'private-captcha-js';

const client = createClient({ apiKey: 'your-api-key' });

const result = await client.verify({ solution: 'captcha-solution-from-client' });
if (result.ok()) {
    console.log('Captcha verified!');
}
```

--------------------------------

### Get Organization Properties - cURL

Source: https://docs.privatecaptcha.com/docs/reference/platform-api

Lists properties associated with a specific organization. Supports pagination via `page` and `per_page` query parameters. Returns an array of property objects, each containing an ID, name, and sitekey.

```curl
curl -X GET "https://api.privatecaptcha.com/org/vDWtASYqrB/properties?page=1&per_page=10" \
  -H "X-API-Key: your-portal-api-key"
```
Tokens:
Raw