# Django REST reCAPTCHA
**Django REST reCAPTCHA v2 and v3 field serializer**
[](https://github.com/sponsors/llybin)
[](https://github.com/llybin/drf-recaptcha/actions)
[](https://www.codacy.com/app/llybin/drf-recaptcha?utm_source=github.com&utm_medium=referral&utm_content=llybin/drf-recaptcha&utm_campaign=Badge_Grade)
[](https://www.codacy.com/app/llybin/drf-recaptcha?utm_source=github.com&utm_medium=referral&utm_content=llybin/drf-recaptcha&utm_campaign=Badge_Coverage)
[](https://github.com/astral-sh/ruff)
[](https://pypi.org/project/drf-recaptcha/)
[](https://pypi.org/project/drf-recaptcha/)
[](https://pypi.org/project/drf-recaptcha/)
## Requirements
* Python: 3.10, 3.11, 3.12
* Django: 4.2, 5.0, 5.1
* DRF: 3.14, 3.15
## Installation
1. [Sign up for reCAPTCHA](https://www.google.com/recaptcha/)
2. Install with `pip install drf-recaptcha`
3. Add `"drf_recaptcha"` to your `INSTALLED_APPS` settings.
4. Set in settings `DRF_RECAPTCHA_SECRET_KEY`
```python
INSTALLED_APPS = [
...,
"drf_recaptcha",
...,
]
...
DRF_RECAPTCHA_SECRET_KEY = "YOUR SECRET KEY"
```
## Usage
```python
from rest_framework.serializers import Serializer, ModelSerializer
from drf_recaptcha.fields import ReCaptchaV2Field, ReCaptchaV3Field
from feedback.models import Feedback
class V2Serializer(Serializer):
recaptcha = ReCaptchaV2Field()
...
class GetOTPView(APIView):
def post(self, request):
serializer = V2Serializer(data=request.data, context={"request": request})
serializer.is_valid(raise_exception=True)
...
class V3Serializer(Serializer):
recaptcha = ReCaptchaV3Field(action="example")
...
class V3WithScoreSerializer(Serializer):
recaptcha = ReCaptchaV3Field(
action="example",
required_score=0.6,
)
...
class GetReCaptchaScore(APIView):
def post(self, request):
serializer = V3WithScoreSerializer(data=request.data, context={"request": request})
serializer.is_valid()
score = serializer.fields['recaptcha'].score
...
class FeedbackSerializer(ModelSerializer):
recaptcha = ReCaptchaV2Field()
class Meta:
model = Feedback
fields = ("phone", "full_name", "email", "comment", "recaptcha")
def validate(self, attrs):
attrs.pop("recaptcha")
...
return attrs
class DynamicContextSecretKey(APIView):
def post(self, request):
if request.platform == "android":
recaptcha_secret_key = "SPECIAL_FOR_ANDROID"
else:
recaptcha_secret_key = "SPECIAL_FOR_IOS"
serializer = WithReCaptchaSerializer(
data=request.data,
context={
"request": request,
"recaptcha_secret_key": recaptcha_secret_key,
},
)
serializer.is_valid(raise_exception=True)
...
class DynamicContextSecretKey(GenericAPIView):
serializer_class = WithReCaptchaSerializer
def get_serializer_context(self):
if self.request.platform == "android":
recaptcha_secret_key = "SPECIAL_FOR_ANDROID"
else:
recaptcha_secret_key = "SPECIAL_FOR_IOS"
context = super().get_serializer_context()
context.update({"recaptcha_secret_key": recaptcha_secret_key})
return context
class MobileSerializer(Serializer):
recaptcha = ReCaptchaV3Field(secret_key="SPECIAL_MOBILE_KEY", action="feedback")
...
```
## Settings
`DRF_RECAPTCHA_SECRET_KEY` - set your Google reCAPTCHA secret key. Type: str.
`DRF_RECAPTCHA_DEFAULT_V3_SCORE` - by default: `0.5`. Type: float.
`DRF_RECAPTCHA_ACTION_V3_SCORES` - by default: `{}`. Type: dict. You can define specific score for each action e.g.
`{"login": 0.6, "feedback": 0.3}`
`DRF_RECAPTCHA_DOMAIN` - by default: `www.google.com`. Type: str.
`DRF_RECAPTCHA_PROXY` - by default: `{}`. Type: dict. e.g.
`{'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'}`
`DRF_RECAPTCHA_VERIFY_REQUEST_TIMEOUT` - by default: `10`. Type: int.
### Priority of secret_key value
1. settings `DRF_RECAPTCHA_SECRET_KEY`
2. the argument `secret_key` of field
3. request.context["recaptcha_secret_key"]
### Silence the check error
If you need to disable the error, you can do so using the django settings.
```python
SILENCED_SYSTEM_CHECKS = ['drf_recaptcha.checks.recaptcha_system_check']
```
## reCAPTCHA v3
Validation is passed if the score value returned by Google is greater than or equal to required score.
Required score value: `0.0 - 1.0`
### Priority of score value
If not defined or zero in current item then value from next item.
1. Value for action in settings `DRF_RECAPTCHA_ACTION_V3_SCORES`
2. Value in argument `required_score` of field
3. Default value in settings `DRF_RECAPTCHA_DEFAULT_V3_SCORE`
4. Default value `0.5`
## Testing
Set `DRF_RECAPTCHA_TESTING=True` in settings, no request to Google, no warnings, `DRF_RECAPTCHA_SECRET_KEY` is not
required, set returning verification result in setting below.
`DRF_RECAPTCHA_TESTING_PASS=True|False` - all responses are pass, default `True`.
Use `from django.test import override_settings`
## Credits
[django-recaptcha](https://github.com/praekelt/django-recaptcha)
reCAPTCHA copyright 2012 Google.
Raw data
{
"_id": null,
"home_page": "https://github.com/llybin/drf-recaptcha",
"name": "drf-recaptcha",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "django, drf, rest, django-rest-framework, reCAPTCHA, reCAPTCHA v2, reCAPTCHA v3",
"author": "Lev Lybin",
"author_email": "lev.lybin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9e/de/d51d44b509a54559a73c1435434f3ab3467f66d91ef9d2cd15459faa1f4e/drf_recaptcha-4.0.2.tar.gz",
"platform": null,
"description": "# Django REST reCAPTCHA\n\n**Django REST reCAPTCHA v2 and v3 field serializer**\n\n[](https://github.com/sponsors/llybin)\n[](https://github.com/llybin/drf-recaptcha/actions)\n[](https://www.codacy.com/app/llybin/drf-recaptcha?utm_source=github.com&utm_medium=referral&utm_content=llybin/drf-recaptcha&utm_campaign=Badge_Grade)\n[](https://www.codacy.com/app/llybin/drf-recaptcha?utm_source=github.com&utm_medium=referral&utm_content=llybin/drf-recaptcha&utm_campaign=Badge_Coverage)\n[](https://github.com/astral-sh/ruff)\n[](https://pypi.org/project/drf-recaptcha/)\n[](https://pypi.org/project/drf-recaptcha/)\n[](https://pypi.org/project/drf-recaptcha/)\n\n\n## Requirements\n\n* Python: 3.10, 3.11, 3.12\n* Django: 4.2, 5.0, 5.1\n* DRF: 3.14, 3.15\n\n## Installation\n\n1. [Sign up for reCAPTCHA](https://www.google.com/recaptcha/)\n2. Install with `pip install drf-recaptcha`\n3. Add `\"drf_recaptcha\"` to your `INSTALLED_APPS` settings.\n4. Set in settings `DRF_RECAPTCHA_SECRET_KEY`\n\n```python\nINSTALLED_APPS = [\n ...,\n \"drf_recaptcha\",\n ...,\n]\n\n...\n\nDRF_RECAPTCHA_SECRET_KEY = \"YOUR SECRET KEY\"\n```\n\n## Usage\n\n```python\nfrom rest_framework.serializers import Serializer, ModelSerializer\nfrom drf_recaptcha.fields import ReCaptchaV2Field, ReCaptchaV3Field\nfrom feedback.models import Feedback\n\n\nclass V2Serializer(Serializer):\n recaptcha = ReCaptchaV2Field()\n ...\n\n\nclass GetOTPView(APIView):\n def post(self, request):\n serializer = V2Serializer(data=request.data, context={\"request\": request})\n serializer.is_valid(raise_exception=True)\n ...\n\n\nclass V3Serializer(Serializer):\n recaptcha = ReCaptchaV3Field(action=\"example\")\n ...\n\n\nclass V3WithScoreSerializer(Serializer):\n recaptcha = ReCaptchaV3Field(\n action=\"example\",\n required_score=0.6,\n )\n ...\n\n\nclass GetReCaptchaScore(APIView):\n def post(self, request):\n serializer = V3WithScoreSerializer(data=request.data, context={\"request\": request})\n serializer.is_valid()\n score = serializer.fields['recaptcha'].score\n ...\n\n\nclass FeedbackSerializer(ModelSerializer):\n recaptcha = ReCaptchaV2Field()\n\n class Meta:\n model = Feedback\n fields = (\"phone\", \"full_name\", \"email\", \"comment\", \"recaptcha\")\n\n def validate(self, attrs):\n attrs.pop(\"recaptcha\")\n ...\n return attrs\n\n\nclass DynamicContextSecretKey(APIView):\n def post(self, request):\n if request.platform == \"android\":\n recaptcha_secret_key = \"SPECIAL_FOR_ANDROID\"\n else:\n recaptcha_secret_key = \"SPECIAL_FOR_IOS\"\n serializer = WithReCaptchaSerializer(\n data=request.data,\n context={\n \"request\": request,\n \"recaptcha_secret_key\": recaptcha_secret_key,\n },\n )\n serializer.is_valid(raise_exception=True)\n ...\n\n\nclass DynamicContextSecretKey(GenericAPIView):\n serializer_class = WithReCaptchaSerializer\n\n def get_serializer_context(self):\n if self.request.platform == \"android\":\n recaptcha_secret_key = \"SPECIAL_FOR_ANDROID\"\n else:\n recaptcha_secret_key = \"SPECIAL_FOR_IOS\"\n context = super().get_serializer_context()\n context.update({\"recaptcha_secret_key\": recaptcha_secret_key})\n return context\n\n\nclass MobileSerializer(Serializer):\n recaptcha = ReCaptchaV3Field(secret_key=\"SPECIAL_MOBILE_KEY\", action=\"feedback\")\n ...\n```\n\n## Settings\n\n`DRF_RECAPTCHA_SECRET_KEY` - set your Google reCAPTCHA secret key. Type: str.\n\n`DRF_RECAPTCHA_DEFAULT_V3_SCORE` - by default: `0.5`. Type: float.\n\n`DRF_RECAPTCHA_ACTION_V3_SCORES` - by default: `{}`. Type: dict. You can define specific score for each action e.g.\n`{\"login\": 0.6, \"feedback\": 0.3}`\n\n`DRF_RECAPTCHA_DOMAIN` - by default: `www.google.com`. Type: str.\n\n`DRF_RECAPTCHA_PROXY` - by default: `{}`. Type: dict. e.g.\n`{'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'}`\n\n`DRF_RECAPTCHA_VERIFY_REQUEST_TIMEOUT` - by default: `10`. Type: int.\n\n### Priority of secret_key value\n\n1. settings `DRF_RECAPTCHA_SECRET_KEY`\n2. the argument `secret_key` of field\n3. request.context[\"recaptcha_secret_key\"]\n\n### Silence the check error\n\nIf you need to disable the error, you can do so using the django settings.\n\n```python\nSILENCED_SYSTEM_CHECKS = ['drf_recaptcha.checks.recaptcha_system_check']\n```\n\n## reCAPTCHA v3\n\nValidation is passed if the score value returned by Google is greater than or equal to required score.\n\nRequired score value: `0.0 - 1.0`\n\n### Priority of score value\n\nIf not defined or zero in current item then value from next item.\n\n1. Value for action in settings `DRF_RECAPTCHA_ACTION_V3_SCORES`\n2. Value in argument `required_score` of field\n3. Default value in settings `DRF_RECAPTCHA_DEFAULT_V3_SCORE`\n4. Default value `0.5`\n\n## Testing\n\nSet `DRF_RECAPTCHA_TESTING=True` in settings, no request to Google, no warnings, `DRF_RECAPTCHA_SECRET_KEY` is not\nrequired, set returning verification result in setting below.\n\n`DRF_RECAPTCHA_TESTING_PASS=True|False` - all responses are pass, default `True`.\n\nUse `from django.test import override_settings`\n\n## Credits\n\n[django-recaptcha](https://github.com/praekelt/django-recaptcha)\n\nreCAPTCHA copyright 2012 Google.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django rest framework recaptcha field serializer",
"version": "4.0.2",
"project_urls": {
"Homepage": "https://github.com/llybin/drf-recaptcha",
"Repository": "https://github.com/llybin/drf-recaptcha"
},
"split_keywords": [
"django",
" drf",
" rest",
" django-rest-framework",
" recaptcha",
" recaptcha v2",
" recaptcha v3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "469dfaeef6ee72832b5773409f24eb54b635ea9d727cae77e082391be21ac632",
"md5": "1a73e83b8fd633d02b733cde19a186f4",
"sha256": "72f2f39bca4a1adb897c696381a098b3e5e5e5d111a7ced98aa15a75e37c1df7"
},
"downloads": -1,
"filename": "drf_recaptcha-4.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a73e83b8fd633d02b733cde19a186f4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9357,
"upload_time": "2024-09-15T11:35:25",
"upload_time_iso_8601": "2024-09-15T11:35:25.251912Z",
"url": "https://files.pythonhosted.org/packages/46/9d/faeef6ee72832b5773409f24eb54b635ea9d727cae77e082391be21ac632/drf_recaptcha-4.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9eded51d44b509a54559a73c1435434f3ab3467f66d91ef9d2cd15459faa1f4e",
"md5": "aa08090e725fb81301d8445be618454e",
"sha256": "68fb90860f53374b4732a22b6980d7ac1cbb006d444d527d25f39d95392be99e"
},
"downloads": -1,
"filename": "drf_recaptcha-4.0.2.tar.gz",
"has_sig": false,
"md5_digest": "aa08090e725fb81301d8445be618454e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9664,
"upload_time": "2024-09-15T11:35:27",
"upload_time_iso_8601": "2024-09-15T11:35:27.117459Z",
"url": "https://files.pythonhosted.org/packages/9e/de/d51d44b509a54559a73c1435434f3ab3467f66d91ef9d2cd15459faa1f4e/drf_recaptcha-4.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-15 11:35:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "llybin",
"github_project": "drf-recaptcha",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "drf-recaptcha"
}
JSON
