Add GET /v1/credentials/totp to list recent 2FA codes per org (#3770)

skyvern/forge/sdk/db/client.py

@@ -2799,13 +2799,17 @@ class AgentDB:
         totp_identifier: str,
         valid_lifespan_minutes: int = settings.TOTP_LIFESPAN_MINUTES,
         otp_type: OTPType | None = None,
+        workflow_run_id: str | None = None,
+        limit: int | None = None,
     ) -> list[TOTPCode]:
         """
         1. filter by:
         - organization_id
         - totp_identifier
+        - workflow_run_id (optional)
         2. make sure created_at is within the valid lifespan
         3. sort by task_id/workflow_id/workflow_run_id nullslast and created_at desc
+        4. apply an optional limit at the DB layer
         """
         all_null = and_(
             TOTPCodeModel.task_id.is_(None),
@@ -2821,10 +2825,45 @@ class AgentDB:
             )
             if otp_type:
                 query = query.filter(TOTPCodeModel.otp_type == otp_type)
+            if workflow_run_id is not None:
+                query = query.filter(TOTPCodeModel.workflow_run_id == workflow_run_id)
             query = query.order_by(asc(all_null), TOTPCodeModel.created_at.desc())
+            if limit is not None:
+                query = query.limit(limit)
             totp_code = (await session.scalars(query)).all()
             return [TOTPCode.model_validate(totp_code) for totp_code in totp_code]
 
+    async def get_recent_otp_codes(
+        self,
+        organization_id: str,
+        limit: int = 50,
+        valid_lifespan_minutes: int = settings.TOTP_LIFESPAN_MINUTES,
+        otp_type: OTPType | None = None,
+        workflow_run_id: str | None = None,
+    ) -> list[TOTPCode]:
+        """
+        Return recent otp codes for an organization ordered by newest first with optional
+        workflow_run_id filtering.
+        """
+        all_null = and_(
+            TOTPCodeModel.task_id.is_(None),
+            TOTPCodeModel.workflow_id.is_(None),
+            TOTPCodeModel.workflow_run_id.is_(None),
+        )
+        async with self.Session() as session:
+            query = (
+                select(TOTPCodeModel)
+                .filter_by(organization_id=organization_id)
+                .filter(TOTPCodeModel.created_at > datetime.utcnow() - timedelta(minutes=valid_lifespan_minutes))
+            )
+            if otp_type:
+                query = query.filter(TOTPCodeModel.otp_type == otp_type)
+            if workflow_run_id is not None:
+                query = query.filter(TOTPCodeModel.workflow_run_id == workflow_run_id)
+            query = query.order_by(asc(all_null), TOTPCodeModel.created_at.desc()).limit(limit)
+            totp_codes = (await session.scalars(query)).all()
+            return [TOTPCode.model_validate(totp_code) for totp_code in totp_codes]
+
     async def create_otp_code(
         self,
         organization_id: str,

skyvern/forge/sdk/routes/credentials.py

@@ -124,6 +124,65 @@ async def send_totp_code(
     )
 
 
+@base_router.get(
+    "/credentials/totp",
+    response_model=list[TOTPCode],
+    summary="List TOTP codes",
+    description="Retrieves recent TOTP codes for the current organization.",
+    tags=["Credentials"],
+    openapi_extra={
+        "x-fern-sdk-method-name": "get_totp_codes",
+    },
+    include_in_schema=False,
+)
+@base_router.get(
+    "/credentials/totp/",
+    response_model=list[TOTPCode],
+    include_in_schema=False,
+)
+async def get_totp_codes(
+    curr_org: Organization = Depends(org_auth_service.get_current_org),
+    totp_identifier: str | None = Query(
+        None,
+        description="Filter by TOTP identifier such as an email or phone number.",
+        examples=["john.doe@example.com"],
+    ),
+    workflow_run_id: str | None = Query(
+        None,
+        description="Filter by workflow run ID.",
+        examples=["wr_123456"],
+    ),
+    otp_type: OTPType | None = Query(
+        None,
+        description="Filter by OTP type (e.g. totp, magic_link).",
+        examples=[OTPType.TOTP.value],
+    ),
+    limit: int = Query(
+        50,
+        ge=1,
+        le=200,
+        description="Maximum number of codes to return.",
+    ),
+) -> list[TOTPCode]:
+    if totp_identifier:
+        codes = await app.DATABASE.get_otp_codes(
+            organization_id=curr_org.organization_id,
+            totp_identifier=totp_identifier,
+            otp_type=otp_type,
+            workflow_run_id=workflow_run_id,
+            limit=limit,
+        )
+    else:
+        codes = await app.DATABASE.get_recent_otp_codes(
+            organization_id=curr_org.organization_id,
+            limit=limit,
+            otp_type=otp_type,
+            workflow_run_id=workflow_run_id,
+        )
+
+    return codes
+
+
 @legacy_base_router.post("/credentials")
 @legacy_base_router.post("/credentials/", include_in_schema=False)
 @base_router.post(