documentation for totp (Skyvern-AI#841)

docs/running-tasks/advanced-features.mdx

@@ -21,9 +21,12 @@ Body:
 
 ## Time-based One-time Password (TOTP)
 
-Skyvern supports one-time password (see https://www.twilio.com/docs/glossary/totp for more information) by fetching it from your endpoint. You can pass `totp_verification_url` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). Inside this endpoint hosted by you, you have to conform to the following schema:
+Skyvern supports one-time password (see https://www.twilio.com/docs/glossary/totp for more information), also knwon as 2FA/MFA, in two ways: 1) Skyvern gets the code from your endpoint 2) You push the the code to Skyvern.
 
-### Set Up Your TOTP Endpoint
+### Get Code From Your Endpoint
+You can pass `totp_verification_url` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). Inside this endpoint hosted by you, you have to conform to the following schema:
+
+#### Set Up Your TOTP Endpoint
 For websites that requires a verification code to complete a task, you have to set up a TOTP endpoint for Skyvern to fetch the verification code.
 
 Here's the TOTP endpoint contract you should use:
@@ -39,7 +42,7 @@ Response:
 | task_id | String | yes | tsk_123 | The task ID that needs the verification to be done |
 | verification_code | String | no | 123456 | The verification code |
 
-### Validate The Sender of The Request
+#### Validate The Sender of The Request
 Same as the webhook API, your server needs to make sure it’s Skyvern that’s making the request.
 
 - a python example for how to generate and validate the signature:
@@ -54,3 +57,103 @@ def validate_skyvern_request_headers(request: Request) -> bool:
 ```
 
 SKYVERN_API_KEY: this is the [api key](/running-tasks/introduction) specific to your organization
+
+### Push Code To Skyvern
+You can pass `totp_identifier` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). When the TOTP code arrives at your inbox or as a text message, all you need to do is to send the email/message (Gmail + Zapier integration can be a good solution to set up email forwarding) to Skyvern's TOTP receiver endpoint (see below)
+
+#### Skyvern's TOTP Endpoint
+This endpoint takes your TOTP/2FA/MFA code, stores it in Skyvern’s database and uses it while running tasks/workflows.
+
+Request type: `POST`
+
+Endpoint url: `https://api.skyvern.com/api/v1/totp`
+
+Authentication: same as other Skyvern APIs, you need to pass your api key with the `x-api-key` header.
+
+Request data:
+| field | required | type | example | description |
+| --- | --- | --- | --- | --- |
+| totp_identifier | yes | string | An email address or phone number which received the code | this is a required field as this is the best way for skyvern to know what the identifier  |
+| content | yes | string |  | the email content of a 2FA email; the text message for the verification code |
+| task_id | no | string | tsk_22222222 | if passed, this will be used to help skyvern locate the totp code more accurately |
+| workflow_id | no | string | wpid_12345 | used to help better locate the totp code accurately for your workflow |
+| source | no | string | email, phone, app, etc |  |
+| expired_at | no | string |  | if provided, skyvern uses this time to decide if the code is valid or not |
+
+#### Forwarding Your Email To Skyvern (Gmail + Zapier)
+This setup requires a Zapier pro plan account.
+
+**Step 1. Create a Zapier Zap**
+
+Go to https://zapier.com/app/home and create new Zaps
+<p align="center">
+  <img src="images/totp/create_zap.png"/>
+</p>
+
+In the newly created Zap draft, Click the “Trigger” button
+<p align="center">
+  <img src="images/totp/create_zap_trigger.png"/>
+</p>
+
+Click `Email by Zapier`
+<p align="center">
+  <img src="images/totp/create_zap_trigger.png"/>
+</p>
+
+In the Email “Setup”, pick `New Inbound Email` in the `Trigger event` selection. Click `Continue` to complete the “Setup”
+<p align="center">
+  <img src="images/totp/create_zap_email_setup.png"/>
+</p>
+
+In Email “Configure”, create an email address which will be used to forward emails for TOTP codes. Click “Continue”.
+<p align="center">
+  <img src="images/totp/create_zap_input_email.png"/>
+</p>
+
+Let’s add the Action to complete the Zapier setup before coming back to test it. Click the “Action” button and add `Webhooks by Zapier`
+<p align="center">
+  <img src="images/totp/create_zap_action.png"/>
+</p>
+
+<p align="center">
+  <img src="images/totp/create_zap_webhook.png"/>
+</p>
+
+In the Setup, choose “POST” under the `Action event` selection. Then click “Continue”.
+<p align="center">
+  <img src="images/totp/create_zap_action_event_post.png"/>
+</p>
+
+In the “Configure”, set up these in order to make a POST request to Skyvern’s TOTP API:
+
+- URL: [`http://54.163.41.95:8000/api/v1/totp`](http://54.163.41.95:8000/api/v1/totp)
+- Payload Type: json
+- Data:
+    - totp_identifier: choose `Raw To Email` after clicking the “+” sign
+    - content: choose `Body Plain` after clicking the “+” sign
+    - source: email
+- Headers:
+    - x-api-key: {your Skyvern API key}
+
+<p align="center">
+  <img src="images/totp/create_zap_webhook_complete.png"/>
+</p>
+Click Continue
+
+**Step 2. Add forwarding email and create a filter in Gmail**
+Go to Gmail Settings → Forwarding and POP/IMAP (https://mail.google.com/mail/u/0/#settings/fwdandpop) → click “Add a forwarding address” → enter the zapier email address you just created. There might be some verifications, including a verification email from Zapier, you have to complete here.
+
+After setting up the forwarding email address, go to “Filters and Blocked Addresses” (https://mail.google.com/mail/u/0/#settings/filters). Click “Create a new filter” and set up your email filtering rule for your TOTP (2FA/MFA) emails. Click “Create filter”. Check “Forward it to” and pick the new email address and update filter.
+
+<p align="center">
+  <img src="images/totp/create_email_forwarding.png"/>
+</p>
+
+**Step 3. Test it end to end!**
+You can forward any previous TOTP (2FA/MFA) email to the Zapier email address you created in Step 1.
+
+In Zapier: under the “Test” of the Webhooks action, send a request to test it out. If your test is sccessful, you should see a `A request was sent to Webhooks by Zapier` message
+
+<p align="center">
+  <img src="images/totp/test_end_to_end.png"/>
+</p>

docs/running-tasks/api-spec.mdx

@@ -27,7 +27,8 @@ Production:`https://api.skyvern.com/api/v1/tasks/`
 | navigation_payload | Object | no |         "name": "Chris P. Bacon",<br/>"email": "mailto:[email protected]" | JSON-formatted payload with any “facts” or information that would help the agent perform its job. In the case of navigating an insurance quote, this payload would include any user information to help fill out the insurance flow such as date of birth, or age they got their license, and so on<br/><br/>This can include nested information, and the formatting isn’t validated |
 | proxy_location | String | yes | RESIDENTIAL | Proxy location for the web-browsing request. Please pass RESIDENTIAL as a value |
 | extracted_information_schema | JSON | no |  | Used to enforce a JSON schema spec to be enforced in the data_extraction_goal. Similar to https://json-schema.org/ definition. |
-| totp_verification_url | String | no | https://mywebsite.com/two_factor_code | The url of your TOTP endpoint |
+| totp_verification_url | String | no | https://mywebsite.com/two_factor_code | The url of your TOTP endpoint. If this field is provided, Skyvern will call the url to fetch the TOTP/2FA/MFA code when needed |
+| totp_identifier | String | no | [email protected] / 4155558888 | The email address or the phone number which receives the TOTP/2FA/MFA code. If this field is provided, Skyvern will fetch the code that is pushed to [Skyvern's TOTP API](https://docs.skyvern.com/running-tasks/advanced-features#push-code-to-skyvern) |
 
 ## Example Request (Apply for a job)