From 403b7d215b4bf0da6a4919418a57a7ac7aa705bf Mon Sep 17 00:00:00 2001 From: Shuchang Zheng Date: Mon, 15 Jul 2024 12:33:24 -0700 Subject: [PATCH] totp_verification_url in the task creation API and task cancel API documentation (#605) --- docs/mint.json | 3 +- docs/running-tasks/api-spec.mdx | 8 ++++ docs/running-tasks/totp-verification-code.mdx | 37 +++++++++++++++++++ 3 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 docs/running-tasks/totp-verification-code.mdx diff --git a/docs/mint.json b/docs/mint.json index 723892e3..a6b2d3bd 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -72,6 +72,7 @@ "running-tasks/introduction", "running-tasks/api-spec", "running-tasks/webhooks-faq", + "running-tasks/totp-verification-code", "running-tasks/visualizing-results", "running-tasks/prompting-tips", "running-tasks/advanced-features" @@ -100,4 +101,4 @@ "github": "https://github.com/skyvern-ai/skyvern/", "linkedin": "https://www.linkedin.com/company/skyvern" } -} \ No newline at end of file +} diff --git a/docs/running-tasks/api-spec.mdx b/docs/running-tasks/api-spec.mdx index dc5544fa..1bb263dd 100644 --- a/docs/running-tasks/api-spec.mdx +++ b/docs/running-tasks/api-spec.mdx @@ -27,6 +27,7 @@ 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 | ## Example Request (Apply for a job) @@ -130,3 +131,10 @@ The response is a list of Step Object. | retry_index | Integer | 0 / 1 / 2 / 3 | When a step fails, the retry step will have a retry_index that's larger than 0 | | input_token_count | Integer | 19223 | The number of input tokens used in this step | | output_token_count | Integer | 500 | The number of output tokens generated in this step | + +## Request - Cancel A Task (POST) +A task that's in any of thsese states can be canceled: ["created", "queued", "running"] + +Request type: `POST` + +Production: `https://api.skyvern.com/api/v1/tasks/{task_id}/cancel` diff --git a/docs/running-tasks/totp-verification-code.mdx b/docs/running-tasks/totp-verification-code.mdx new file mode 100644 index 00000000..ddf3325d --- /dev/null +++ b/docs/running-tasks/totp-verification-code.mdx @@ -0,0 +1,37 @@ +--- +title: Time-based One-time Passowrd +description: 'How Skyvern gets the one time password from you?' +--- + +Skyvern supports one-time password by fetching it from your endpoint. You can pass `totp_verification_url` when creating a task. Inside this endpoint hosted by you, you have to conform to the following schema: + +## Set Up Your Time-based One-time Password (TOTP) Endpoint +For websites that requires a verification code (see https://www.twilio.com/docs/glossary/totp for more information) 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: + +Request (POST): +| Parameter | Type | Required? | Sample Value | Description | +| --- | --- | --- | --- | --- | +| task_id | String | yes | tsk_123 | The task ID that needs the verification to be done | + +Response: +| Parameter | Type | Required? | Sample Value | Description | +| 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 +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: + +```python +def validate_skyvern_request_headers(request: Request) -> bool: + header_skyvern_signature = request.headers["x-skyvern-signature"] + payload = request.body() # this is a bytes + hash_obj = hmac.new(SKYVERN_API_KEY.encode("utf-8"), msg=payload, digestmod=hashlib.sha256) + client_generated_signature = hash_obj.hexdigest() + return header_skyvern_signature == client_generated_signature +``` + +SKYVERN_API_KEY: this is the [api key](/running-tasks/introduction) specific to your organization