django-arcaptcha

Arcaptcha integration for Django REST Framework. Works exactly like django-recaptcha — add one line to any serializer.

Requirements

• Python 3.10+
• Django 4.2+
• Django REST Framework 3.14+
• arcaptcha-python 0.1.2+

Installation

pip install django-arcaptcha

settings.py

INSTALLED_APPS = [
    ...
    "arcaptcha",
]

# Get your keys at https://arcaptcha.ir
ARCAPTCHA_SITE_KEY   = "your_site_key"
ARCAPTCHA_SECRET_KEY = "your_secret_key"

Verify your setup:

python manage.py check --deploy

Usage

Option 1 — Field (explicit, one line)

from arcaptcha import ArcaptchaField

class LoginSerializer(serializers.Serializer):
    email    = serializers.EmailField()
    password = serializers.CharField(write_only=True)
    captcha  = ArcaptchaField()

Option 2 — Mixin (automatic injection)

from arcaptcha import ArcaptchaMixin

class LoginSerializer(ArcaptchaMixin, serializers.Serializer):
    email    = serializers.EmailField()
    password = serializers.CharField(write_only=True)
    # `captcha` field is injected automatically

Option 3 — Validator (anywhere outside a serializer)

from arcaptcha import ArcaptchaValidator

# in a view, task, or any callable
ArcaptchaValidator()(request.data["captcha"])

What the client sends

POST /api/auth/login/
{
    "email":    "alice@example.com",
    "password": "secret",
    "captcha":  "<token-from-arcaptcha-widget>"
}

Error responses

// Invalid token → HTTP 400
{"captcha": ["Invalid or expired captcha. Please try again."]}

// Service down → HTTP 400
{"captcha": ["Captcha verification is temporarily unavailable. Please try again later."]}

All settings

Testing in your project

Option A — disable in test settings (simplest)

# settings/test.py
ARCAPTCHA_DISABLE = True

Option B — mock the verify call per test

from unittest.mock import patch

@patch("arcaptcha.validators.verify_arcaptcha", return_value=True)
def test_login(mock_verify, api_client):
    res = api_client.post("/api/auth/login/", {
        "email": "a@b.com", "password": "secret", "captcha": "any"
    })
    assert res.status_code == 200

Contributing

git clone https://github.com/rassoulshah/django-arcaptcha
cd django-arcaptcha
pip install -e ".[dev]"
pytest

License

MIT