Add API tokens and OAuth2 client support for external integrations

- Personal API tokens (model, user-settings UI, admin, management command,
  DRF auth class) for non-interactive API access from automations like n8n.
  Raw token shown once; only a SHA-256 hash is stored; last_used_at writes
  are throttled.
- OAuth2 authorization server via django-oauth-toolkit with authorization
  server metadata and optional, off-by-default Dynamic Client Registration
  (RFC 7591), so remote OAuth/MCP clients can authenticate and self-register.
- Tests for token auth, DCR gating and the management commands, plus
  .env.example and README documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/apps/api/authentication.py

@@ -0,0 +1,64 @@
+from datetime import timedelta
+
+from django.conf import settings
+from django.utils import timezone
+from rest_framework.authentication import BaseAuthentication, get_authorization_header
+from rest_framework.exceptions import AuthenticationFailed
+
+from apps.users.models import APIToken
+
+
+class APITokenAuthentication(BaseAuthentication):
+    keyword = "Token"
+
+    def authenticate(self, request):
+        auth = get_authorization_header(request).split()
+        if not auth or auth[0].lower() != self.keyword.lower().encode():
+            return None
+
+        if len(auth) != 2:
+            raise AuthenticationFailed("Invalid API token header.")
+
+        try:
+            raw_token = auth[1].decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise AuthenticationFailed("Invalid API token header.") from exc
+
+        # Only claim tokens carrying our prefix; otherwise return None so the
+        # request falls through to other authenticators (e.g. DRF's built-in
+        # TokenAuthentication, which shares the "Token" keyword).
+        if not raw_token.startswith(APIToken.TOKEN_PREFIX):
+            return None
+
+        try:
+            token_key, token_secret = APIToken.parse_raw_token(raw_token)
+        except ValueError as exc:
+            raise AuthenticationFailed("Invalid API token.") from exc
+
+        token = APIToken.objects.select_related("user").filter(token_key=token_key).first()
+        if token is None or not token.check_secret(token_secret):
+            raise AuthenticationFailed("Invalid API token.")
+        if token.revoked_at is not None:
+            raise AuthenticationFailed("API token has been revoked.")
+        if token.is_expired():
+            raise AuthenticationFailed("API token has expired.")
+        if not token.user.is_active:
+            raise AuthenticationFailed("User account is disabled.")
+
+        self._touch_last_used(token)
+        return (token.user, token)
+
+    @staticmethod
+    def _touch_last_used(token):
+        # Avoid a write on every request: only refresh once per interval.
+        now = timezone.now()
+        interval = settings.API_TOKEN_LAST_USED_UPDATE_INTERVAL
+        if (
+            token.last_used_at is None
+            or (now - token.last_used_at) >= timedelta(seconds=interval)
+        ):
+            token.last_used_at = now
+            token.save(update_fields=["last_used_at"])
+
+    def authenticate_header(self, request):
+        return self.keyword

app/apps/api/tests/test_authentication.py

@@ -0,0 +1,109 @@
+from datetime import timedelta
+
+from django.contrib.auth import get_user_model
+from django.test import RequestFactory, TestCase, override_settings
+from django.utils import timezone
+from rest_framework.exceptions import AuthenticationFailed
+
+from apps.api.authentication import APITokenAuthentication
+from apps.users.models import APIToken
+
+
+class APITokenAuthenticationTests(TestCase):
+    def setUp(self):
+        self.factory = RequestFactory()
+        self.authentication = APITokenAuthentication()
+        self.user = get_user_model().objects.create_user(
+            email="automation@example.com",
+            password="test-password",
+        )
+
+    def test_returns_none_without_token_header(self):
+        request = self.factory.get("/api/accounts/")
+        self.assertIsNone(self.authentication.authenticate(request))
+
+    def test_authenticates_valid_api_token(self):
+        token, raw_token = APIToken.objects.create_token(user=self.user, name="n8n")
+        request = self.factory.get(
+            "/api/accounts/",
+            HTTP_AUTHORIZATION=f"Token {raw_token}",
+        )
+
+        authenticated_user, authenticated_token = self.authentication.authenticate(request)
+
+        self.assertEqual(authenticated_user, self.user)
+        self.assertEqual(authenticated_token.pk, token.pk)
+        token.refresh_from_db()
+        self.assertIsNotNone(token.last_used_at)
+
+    def test_rejects_expired_api_token(self):
+        token, raw_token = APIToken.objects.create_token(user=self.user, name="n8n")
+        token.expires_at = timezone.now() - timedelta(minutes=1)
+        token.save(update_fields=["expires_at"])
+        request = self.factory.get(
+            "/api/accounts/",
+            HTTP_AUTHORIZATION=f"Token {raw_token}",
+        )
+
+        with self.assertRaisesRegex(AuthenticationFailed, "expired"):
+            self.authentication.authenticate(request)
+
+    def test_rejects_revoked_api_token(self):
+        token, raw_token = APIToken.objects.create_token(user=self.user, name="n8n")
+        token.revoked_at = timezone.now()
+        token.save(update_fields=["revoked_at"])
+        request = self.factory.get(
+            "/api/accounts/",
+            HTTP_AUTHORIZATION=f"Token {raw_token}",
+        )
+
+        with self.assertRaisesRegex(AuthenticationFailed, "revoked"):
+            self.authentication.authenticate(request)
+
+    def test_stores_secret_as_sha256_not_raw(self):
+        token, raw_token = APIToken.objects.create_token(user=self.user, name="n8n")
+        _key, secret = APIToken.parse_raw_token(raw_token)
+
+        self.assertNotIn(secret, token.token_hash)
+        self.assertEqual(len(token.token_hash), 64)
+        self.assertTrue(token.check_secret(secret))
+
+    def test_falls_through_for_non_prefixed_token(self):
+        request = self.factory.get(
+            "/api/accounts/",
+            HTTP_AUTHORIZATION="Token deadbeefdeadbeefdeadbeef",
+        )
+        # Not our prefix: return None so another authenticator can handle it.
+        self.assertIsNone(self.authentication.authenticate(request))
+
+    @override_settings(API_TOKEN_LAST_USED_UPDATE_INTERVAL=600)
+    def test_last_used_at_is_throttled_within_interval(self):
+        token, raw_token = APIToken.objects.create_token(user=self.user, name="n8n")
+        request = self.factory.get(
+            "/api/accounts/",
+            HTTP_AUTHORIZATION=f"Token {raw_token}",
+        )
+
+        self.authentication.authenticate(request)
+        token.refresh_from_db()
+        first_used = token.last_used_at
+        self.assertIsNotNone(first_used)
+
+        self.authentication.authenticate(request)
+        token.refresh_from_db()
+        self.assertEqual(token.last_used_at, first_used)
+
+    @override_settings(API_TOKEN_LAST_USED_UPDATE_INTERVAL=0)
+    def test_last_used_at_updates_after_interval(self):
+        token, raw_token = APIToken.objects.create_token(user=self.user, name="n8n")
+        token.last_used_at = timezone.now() - timedelta(minutes=5)
+        token.save(update_fields=["last_used_at"])
+        stale = token.last_used_at
+        request = self.factory.get(
+            "/api/accounts/",
+            HTTP_AUTHORIZATION=f"Token {raw_token}",
+        )
+
+        self.authentication.authenticate(request)
+        token.refresh_from_db()
+        self.assertGreater(token.last_used_at, stale)