diff --git a/docs/images/totp/create_email_forwarding.png b/docs/images/totp/create_email_forwarding.png new file mode 100644 index 00000000..20f43cec Binary files /dev/null and b/docs/images/totp/create_email_forwarding.png differ diff --git a/docs/images/totp/create_zap.png b/docs/images/totp/create_zap.png new file mode 100644 index 00000000..ed5e1588 Binary files /dev/null and b/docs/images/totp/create_zap.png differ diff --git a/docs/images/totp/create_zap_action.png b/docs/images/totp/create_zap_action.png new file mode 100644 index 00000000..b57f8da0 Binary files /dev/null and b/docs/images/totp/create_zap_action.png differ diff --git a/docs/images/totp/create_zap_action_event_post.png b/docs/images/totp/create_zap_action_event_post.png new file mode 100644 index 00000000..5438345f Binary files /dev/null and b/docs/images/totp/create_zap_action_event_post.png differ diff --git a/docs/images/totp/create_zap_email.png b/docs/images/totp/create_zap_email.png new file mode 100644 index 00000000..1862ae85 Binary files /dev/null and b/docs/images/totp/create_zap_email.png differ diff --git a/docs/images/totp/create_zap_email_setup.png b/docs/images/totp/create_zap_email_setup.png new file mode 100644 index 00000000..1249bded Binary files /dev/null and b/docs/images/totp/create_zap_email_setup.png differ diff --git a/docs/images/totp/create_zap_input_email.png b/docs/images/totp/create_zap_input_email.png new file mode 100644 index 00000000..2d78c2f8 Binary files /dev/null and b/docs/images/totp/create_zap_input_email.png differ diff --git a/docs/images/totp/create_zap_trigger.png b/docs/images/totp/create_zap_trigger.png new file mode 100644 index 00000000..a7d0b986 Binary files /dev/null and b/docs/images/totp/create_zap_trigger.png differ diff --git a/docs/images/totp/create_zap_webhook.png b/docs/images/totp/create_zap_webhook.png new file mode 100644 index 00000000..697347ea Binary files /dev/null and b/docs/images/totp/create_zap_webhook.png differ diff --git a/docs/images/totp/create_zap_webhook_complete.png b/docs/images/totp/create_zap_webhook_complete.png new file mode 100644 index 00000000..bdd580e7 Binary files /dev/null and b/docs/images/totp/create_zap_webhook_complete.png differ diff --git a/docs/images/totp/test_end_to_end.png b/docs/images/totp/test_end_to_end.png new file mode 100644 index 00000000..8dd22a26 Binary files /dev/null and b/docs/images/totp/test_end_to_end.png differ diff --git a/docs/running-tasks/advanced-features.mdx b/docs/running-tasks/advanced-features.mdx index 45dff927..e858e37c 100644 --- a/docs/running-tasks/advanced-features.mdx +++ b/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 +

+ +

+ +In the newly created Zap draft, Click the “Trigger” button +

+ +

+ +Click `Email by Zapier` +

+ +

+ +In the Email “Setup”, pick `New Inbound Email` in the `Trigger event` selection. Click `Continue` to complete the “Setup” +

+ +

+ +In Email “Configure”, create an email address which will be used to forward emails for TOTP codes. Click “Continue”. +

+ +

+ +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` +

+ +

+ +

+ +

+ +In the Setup, choose “POST” under the `Action event` selection. Then click “Continue”. +

+ +

+ +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} + +

+ +

+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. + +

+ +

+ +**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 + +

+ +

diff --git a/docs/running-tasks/api-spec.mdx b/docs/running-tasks/api-spec.mdx index 21f0042d..9d5466ec 100644 --- a/docs/running-tasks/api-spec.mdx +++ b/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",
"email": "mailto:chris@pbacon.com" | 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

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 | myemail@example.com / 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)