From 0df77872ab649ae565b8139a35070ed6124855f1 Mon Sep 17 00:00:00 2001
From: Kamran Abdul Aziz <kamran@shifteq.com>
Date: Wed, 3 Jun 2026 12:38:01 +0530
Subject: [PATCH] Clarify API key registration fields

---
 api/api/serializers/oauth2_serializers.py | 21 +++++++++++++++++++++
 api/api/views/oauth2_views.py             | 10 +++++++---
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/api/api/serializers/oauth2_serializers.py b/api/api/serializers/oauth2_serializers.py
index 0a79968c90..a209556cd7 100644
--- a/api/api/serializers/oauth2_serializers.py
+++ b/api/api/serializers/oauth2_serializers.py
@@ -9,6 +9,27 @@ class OAuth2RegistrationSerializer(serializers.ModelSerializer):
     class Meta:
         model = OAuth2Registration
         fields = ("name", "description", "email")
+        extra_kwargs = {
+            "name": {
+                "help_text": (
+                    "A unique human-readable name for your application or project. "
+                    "This name must be unique across all registered Openverse API "
+                    "applications."
+                )
+            },
+            "description": {
+                "help_text": (
+                    "A description of what you are trying to achieve with your "
+                    "project using the API. Please provide as much detail as possible."
+                )
+            },
+            "email": {
+                "help_text": (
+                    "A valid email address that Openverse can use to contact you about "
+                    "your use case or data consumption."
+                )
+            },
+        }
 
 
 class OAuth2ApplicationSerializer(serializers.Serializer):
diff --git a/api/api/views/oauth2_views.py b/api/api/views/oauth2_views.py
index 13f94f4a65..38fddf5f19 100644
--- a/api/api/views/oauth2_views.py
+++ b/api/api/views/oauth2_views.py
@@ -49,7 +49,11 @@ class Register(APIView):
     @register
     def post(self, request, format=None):
         """
-        Register an application to access to API via OAuth2.
+        Register an application for access to the Openverse API via OAuth2.
+
+        Provide a unique application `name`, a brief `description`, and an
+        `email` address where Openverse can contact you. The application `name`
+        must be unique across all registered Openverse API applications.
 
         Upon registering, you will receive a `client_id` and `client_secret`,
         which you can then use to authenticate using the standard OAuth2 flow.
@@ -60,8 +64,8 @@ def post(self, request, format=None):
         > - You must keep `client_secret` confidential, as anybody with your
         >   `client_secret` can impersonate your application.
 
-        You must verify your email address by click the link sent to you in an
-        email. Until you do that, the application will be subject to the same
+        You must verify your email address by clicking the link sent to you in
+        an email. Until you do that, the application will be subject to the same
         rate limits as an anonymous user.
         """