Improve TOTP docs & README & Make CLI actually support typer + py3.11 (#2791)
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
This commit is contained in:
Suchintan
@@ -4,10 +4,29 @@ subtitle: Never send your credentials to LLMs.
|
||||
slug: credentials/introduction
|
||||
---
|
||||
|
||||
Agents need access to sensitive information to complete tasks. For example, usernames and passwords to login, credit cards for payments, etc. With Skyvern's credential management tool, you can run agents securely without exposing your credentials to LLMs.
|
||||
Need to give Skyvern access to your credentials? Usernames and passwords, 2FA, credit cards for payments, etc. Skyvern's credential management provides a secure way to manage and use credentials. Agents can then without exposing those credentials to LLMs.
|
||||
|
||||
## Credential Support
|
||||
<CardGroup cols={2}>
|
||||
### 2FA Support (TOTP)
|
||||
|
||||
Many websites require entering a TOTP (2FA/MFA/Verification) code during login. Skyvern has TOTP (2FA/MFA/Verification Code) support natively.
|
||||
|
||||
**Supported authentication methods**:
|
||||
- Phone verification code
|
||||
- Email verification code
|
||||
- Authenticator app
|
||||
- Confirmation link sent to email. Click the link and create an account
|
||||
- One time login link sent to email. Click and login
|
||||
|
||||
If you have any questions about how to set these up, please contact [Skyvern Support](mailto:support@skyvern.com).
|
||||
|
||||
## Credit Card Management
|
||||
|
||||
Skyvern can manage your credit cards and use them to complete tasks.
|
||||
|
||||
**Supported credit card types**:
|
||||
- Visa
|
||||
- Mastercard
|
||||
<CardGroup cols={3}>
|
||||
<Card
|
||||
title="Password Management"
|
||||
icon="key"
|
||||
@@ -22,24 +41,6 @@ Agents need access to sensitive information to complete tasks. For example, user
|
||||
>
|
||||
Manage and use credit cards with Skyvern Agent
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 2FA Support (TOTP)
|
||||
|
||||
Many websites require entering a TOTP (2FA/MFA/Verification) code during login. Skyvern has the TOTP (2FA/MFA/Verification Code) support natively.
|
||||
|
||||
**Supported authentication methods**:
|
||||
- Phone verification code
|
||||
- Email verification code
|
||||
- Authenticator app
|
||||
|
||||
**Coming soon**:
|
||||
- Confirmation link sent to email. Click the link and create an account. (Talk to Skyvern Support if you need this)
|
||||
- One time login link sent to email. Click and login. (Talk to Skyvern Support if you need this)
|
||||
|
||||
See [2FA Support (TOTP)](/credentials/totp) for more details.
|
||||
|
||||
<CardGroup cols={1}>
|
||||
<Card
|
||||
title="2FA Support (TOTP)"
|
||||
icon="pager"
|
||||
@@ -49,14 +50,63 @@ See [2FA Support (TOTP)](/credentials/totp) for more details.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Bitwarden Integration
|
||||
|
||||
Skyvern can integrate with your Bitwarden account. Skyvern agent can read the credentials on the fly to complete tasks while keeping your credentials secure. Skyvern never stores your Bitwarden credentials or sends them to LLMs.
|
||||
## Password Manager Integrations
|
||||
|
||||
See [Bitwarden Integration](/credentials/bitwarden) for more details.
|
||||
If you have your own password manager, Skyvern can integrate with it. Skyvern can read the credentials on the fly to complete tasks while keeping your credentials secure. Skyvern never stores your credentials or sends them to any third parties (including LLMs).
|
||||
|
||||
## Coming Soon
|
||||
(Contact support@skyvern.com if you need any password integration to help us prioritize)
|
||||
**Supported password manager types**:
|
||||
- Bitwarden
|
||||
- 1Password Integration (Private beta)
|
||||
|
||||
- 1Password Integration
|
||||
**Coming Soon**:
|
||||
- LastPass Integration
|
||||
- Keeper Integration
|
||||
- Azure Key Vault Integration
|
||||
|
||||
Contact [Skyvern Support](mailto:support@skyvern.com) if you want access to the private beta for these integrations.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card
|
||||
title="Bitwarden Integration"
|
||||
icon="shield-keyhole"
|
||||
href="/credentials/bitwarden"
|
||||
>
|
||||
Securely manage your passwords with Bitwarden
|
||||
</Card>
|
||||
<Card
|
||||
title="1Password Integration"
|
||||
icon="fingerprint"
|
||||
href="mailto:sales@skyvern.com"
|
||||
>
|
||||
Securely manage your passwords with 1Password (Private beta)
|
||||
</Card>
|
||||
<Card
|
||||
title="LastPass Integration"
|
||||
icon="vault"
|
||||
href="mailto:sales@skyvern.com"
|
||||
>
|
||||
(coming soon) Securely manage your passwords with LastPass
|
||||
</Card>
|
||||
<Card
|
||||
title="Keeper Integration"
|
||||
icon="lock-keyhole"
|
||||
href="mailto:sales@skyvern.com"
|
||||
>
|
||||
(coming soon) Securely manage your passwords with Keeper
|
||||
</Card>
|
||||
<Card
|
||||
title="Azure Key Vault Integration"
|
||||
icon="cloud"
|
||||
href="mailto:sales@skyvern.com"
|
||||
>
|
||||
(coming soon) Securely manage your secrets with Azure Key Vault
|
||||
</Card>
|
||||
<Card
|
||||
title="AWS Secret Manager Integration"
|
||||
icon="key"
|
||||
href="mailto:sales@skyvern.com"
|
||||
>
|
||||
(coming soon) Securely manage your secrets with AWS Secret Manager
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -1,58 +1,32 @@
|
||||
---
|
||||
title: 2FA Support (TOTP)
|
||||
subtitle: How to send 2FA codes (TOTP) to Skyvern
|
||||
subtitle: How to send TOTP codes (2FA/MFA/Verification Code) to Skyvern
|
||||
slug: credentials/totp
|
||||
---
|
||||
|
||||
Skyvern supports one-time password (see https://www.twilio.com/docs/glossary/totp for more information), also known as 2FA/MFA. For Skyvern to get the code, there are three options:
|
||||
- [Option 1: Store your 2FA/MFA secret in Skyvern Credential tool](#option-1-store-your-2famfa-secret-in-the-skyvern-credential-tool)
|
||||
- [Option 2: Skyvern gets the code from your endpoint](#option-2-get-code-from-your-endpoint)
|
||||
- [Option 3: You push the code to Skyvern](#option-3-push-code-to-skyvern)
|
||||
Skyvern supports logging into websites that require a 2FA/MFA/Verification code. There are 5 kinds of 2FA we support today:
|
||||
- [Option 1: Google Authenticator (TOTP)](#option-1-google-authenticator-totp)
|
||||
- [Option 2: Email Verification Code](#option-2-email-verification-code)
|
||||
- [Option 3: Phone Verification Code](#option-3-phone-verification-code)
|
||||
- [Option 4: Let Skyvern get the code from your server (webhook)](#option-4-let-skyvern-get-the-code-from-your-server-webhook)
|
||||
- [Option 5: One Time Login Link](#option-5-one-time-login-link)
|
||||
|
||||
## Option 1: Store your 2FA/MFA secret in the Skyvern Credential tool
|
||||
## Option 1: Google Authenticator (TOTP)
|
||||
|
||||
Save your username and password in [Skyvern Credential](https://app.skyvern.com/credentials) where you can also store your 2FA/MFA key/secret.
|
||||
Step 1: Save your username and password in [Skyvern Credential](https://app.skyvern.com/credentials). See [Password Management](/credentials/passwords#manage-passwords-in-skyvern-cloud) for more details.
|
||||
|
||||
See [Password Management](/credentials/passwords#manage-passwords-in-skyvern-cloud) for more details.
|
||||
## Option 2: Get Code From Your Endpoint
|
||||
You can pass `totp_url` when running [a task](/api-reference/api-reference/agent/run-task) or a [workflow](/api-reference/api-reference/agent/run-workflow). Inside this endpoint hosted by you, you have to conform to the following schema:
|
||||
Step 2: Add your account by manually entering the secret key (extracted from the QR code). Not sure how to get it? [Follow this guide](https://bitwarden.com/help/integrated-authenticator/).
|
||||
|
||||
### Set Up Your TOTP Endpoint
|
||||
For websites that require a verification code to complete a task, you have to set up a TOTP endpoint for Skyvern to fetch the verification code.
|
||||
> 💡 Don't have the key? Contact [Skyvern Support](mailto:support@skyvern.com) and we can help you get it.
|
||||
|
||||
Here's the TOTP endpoint contract you should use:
|
||||
## Option 2: Email Verification Code
|
||||
Email verification codes require you to set up a forwarding rule that forwards these emails to a Skyvern endpoint.
|
||||
|
||||
Request (POST):
|
||||
| Parameter | Type | Required? | Sample Value | Description |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| task_id | String | yes | tsk_123 | The task ID that needs the verification to be done |
|
||||
The forwarding rule can be set up using [Gmail + Zapier](https://zapier.com/app/home) or similar tools. (instructions below)
|
||||
|
||||
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 |
|
||||
> 💡 *Coming Soon*: We plan to provide email forwarding addresses that make this easier to set up
|
||||
|
||||
### 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: you can get the API KEY from [Skyvern Settings](https://app.skyvern.com/settings).
|
||||
|
||||
## Option 3: Push Code To Skyvern
|
||||
Find TOTP API doc [here](/api-reference/api-reference/credentials/send-totp-code).
|
||||
|
||||
You can pass `totp_identifier` when running [a task](/api-reference/api-reference/agent/run-task) or a [workflow](/api-reference/api-reference/agent/run-workflow). When the TOTP code arrives at your inbox, 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 endpoint.
|
||||
You can pass `totp_identifier` when running [a task](/api-reference/api-reference/agent/run-task) or a [workflow](/api-reference/api-reference/agent/run-workflow). When the TOTP code arrives at your inbox, all you need to do is to send the email/message to Skyvern's [TOTP endpoint](/api-reference/api-reference/credentials/send-totp-code).
|
||||
|
||||
### Forwarding Your Email To Skyvern (Gmail + Zapier)
|
||||
This setup requires a Zapier Pro plan account.
|
||||
@@ -132,4 +106,108 @@ In Zapier: under the “Test” of the Webhooks action, send a request to test i
|
||||
|
||||
<p align="center">
|
||||
<img src="../images/totp/test_end_to_end.png"/>
|
||||
</p>
|
||||
</p>
|
||||
|
||||
|
||||
## Option 3: Phone Verification Code
|
||||
|
||||
Phone verification codes are supported the same way as email verification codes. You will need to set up a forwarding rule that forwards these messages to a Skyvern endpoint.
|
||||
|
||||
A good solution to set up this forwarding rule is to use virtual phone number services such as [Twilio](https://www.twilio.com/en-us/docs/usage/tutorials/how-to-use-your-free-trial-account) or [Pilvo](https://www.pilvo.com/en/us/virtual-phone-number).
|
||||
|
||||
|
||||
Make sure you pass `totp_identifier` when running [a task](/api-reference/api-reference/agent/run-task) or a [workflow](/api-reference/api-reference/agent/run-workflow). When the TOTP code arrives at your virtual phone number, all you need to do is to send the message to Skyvern's TOTP endpoint.
|
||||
|
||||
You can use the following code to forward the message to Skyvern:
|
||||
|
||||
```python
|
||||
// Twilio Function to post 2FA data to Skyvern API
|
||||
|
||||
exports.handler = async function(context, event, callback) {
|
||||
const axios = require('axios');
|
||||
const apiUrl = 'https://api.skyvern.com/v1/credentials/totp';
|
||||
const apiKey = '{{your api key}}';
|
||||
const totpIdentifier = '{{your totp identifier (could be phone number)}}';
|
||||
|
||||
const requestBody = {
|
||||
totp_identifier: totpIdentifier,
|
||||
content: event.Body || "Default 2FA message",
|
||||
source: "phone"
|
||||
};
|
||||
|
||||
const response = new Twilio.Response();
|
||||
response.appendHeader('Content-Type', 'application/json');
|
||||
|
||||
try {
|
||||
const apiResponse = await axios.post(apiUrl, requestBody, {
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'x-api-key': apiKey
|
||||
}
|
||||
});
|
||||
|
||||
response.setStatusCode(200);
|
||||
response.setBody({
|
||||
status: 'success',
|
||||
message: '2FA message sent',
|
||||
data: apiResponse.data
|
||||
});
|
||||
} catch (error) {
|
||||
response.setStatusCode(500);
|
||||
response.setBody({
|
||||
status: 'error',
|
||||
message: error.message,
|
||||
details: error.response?.data || null
|
||||
});
|
||||
}
|
||||
|
||||
return callback(null, response);
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
|
||||
## Option 4: Let Skyvern get the code from your server (webhook)
|
||||
You can pass `totp_url` when running [a task](/api-reference/api-reference/agent/run-task) or a [workflow](/api-reference/api-reference/agent/run-workflow). 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:
|
||||
|
||||
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`: you can get the API KEY from [Skyvern Settings](https://app.skyvern.com/settings).
|
||||
|
||||
## Option 5: One Time Login Link
|
||||
|
||||
One time login links are supported by breaking your workflow / task into two parts:
|
||||
1. Login to trigger the one time login link
|
||||
2. Trigger the rest of your task / workflow based on the one time login link as the starting point
|
||||
|
||||
You will need to set up something (e.g. Zapier) that monitors the email inbox for incoming magic links. Once you get the link, you can use it to trigger the rest of your task / workflow.
|
||||
|
||||
When triggering the rest of your task / workflow, you can pass the one time login link as the starting point (e.g. url parameter), and Skyvern will start the new session already logged in.
|
||||
|
||||
BIN
fern/images/performance/webbench_overall.png
Normal file
BIN
fern/images/performance/webbench_overall.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 109 KiB |
BIN
fern/images/performance/webbench_write.png
Normal file
BIN
fern/images/performance/webbench_write.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
Reference in New Issue
Block a user