credential management documentation (#2389)

fern/credentials/bitwarden.mdx

@@ -0,0 +1,48 @@
+---
+title: Bitwarden Integration
+subtitle: How to integrate Bitwarden with Skyvern
+slug: credentials/bitwarden
+---
+
+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.
+
+## How to integrate Bitwarden with Skyvern
+
+### Bitwarden Integration in Skyvern Cloud
+**Step 1. Make a Bitwarden account**
+Go to https://bitwarden.com/ and create an account. <Warning>💡 Make sure you create an account on `bitwarden.com` not `bitwarden.eu`</Warning>
+
+**Step 2: Make sure you have a Bitwarden Organization created**
+1. Log into Bitwarden and navigate to "Admin Console"
+<img src="../images/bitwarden/bitwarden_tutorial_goto_admin.png" />
+
+2. Make sure you have an organization created
+<img src="../images/bitwarden/bitwarden_tutorial_create_organization.png" />
+
+**Step 3: Go to Members and invite suchintan@skyvern.com**
+1. Click on "Members" in the left pane 
+<img src="../images/bitwarden/bitwarden_tutorial_goto_members.png" />
+2. Click on "Invite Member"
+<img src="../images/bitwarden/bitwarden_tutorial_invite_member.png" />
+3. Invite suchintan@skyvern.com
+<img src="../images/bitwarden/bitwarden_tutorial_invite_skyvern.png" />
+
+**Step 4: Create a collection you'd like to share with Skyvern (Skip if you already have a collection of items to share with Skyvern)**
+1. Click New > Create a collection
+<img src="../images/bitwarden/bitwarden_tutorial_create_collection.png" />
+2. Type in a name (helpful to put your name - Skyvern) 
+<img src="../images/bitwarden/bitwarden_tutorial_create_collection_name.png" />
+3. Go to "Access" and add suchintan@skyvern.com 
+<img src="../images/bitwarden/bitwarden_tutorial_create_collection_access.png" />
+
+**Step 5: Grab your collection id and go to Skyvern**
+1. Click into the collection and inspect the url for a collection uuid
+<img src="../images/bitwarden/bitwarden_tutorial_create_collection_uuid.png" />
+2. Create a new workflow in Skyvern. Click on Parameters + add a credential parameter + pick the "Bitwarden" tab. 
+    a. The URL is the website you'd like to navigate to. This can be parameterized by different `input_parameter`
+    b. Enter the collection id above. This can be parameterized by another input parameter
+<img src="../images/bitwarden/bitwarden_tutorial_create_skyvern_workflow.png" />
+3. Create a login block and select the credentials as input paramters and you should be good to go!
+<img src="../images/bitwarden/bitwarden_tutorial_create_skyvern_task_block.png" />
+
+### Bitwarden Integration in Open Source

fern/credentials/credit_cards.mdx

@@ -0,0 +1,81 @@
+---
+title: Manage Credit Cards
+subtitle: How to manage credit cards in Skyvern
+slug: credentials/credit-cards
+---
+
+## Manage credit cards in Skyvern Cloud
+You can go to [Skyvern's Credentials page](https://app.skyvern.com/credentials) to manage your credit cards.
+
+
+**Add a new credit card credential:**
+
+<img src="../images/credential_management/add_credit_card.png" />
+
+<img src="../images/credential_management/add_credit_card_detail.png" />
+
+**Delete a credit card credential:**
+
+Click the trash icon and confirm the deletion. If you do this, the credit card will be deleted from Skyvern PERMANENTLY.
+<img src="../images/credential_management/delete_credit_card.png" />
+
+**Update a credit card credential:**
+<Warning>Skyvern only supports adding and deleting credit cards. To update a credit card, you need to delete the existing credit card and create a new one.</Warning>
+
+## Manage credit cards with Skyvern's API or SDK
+We also have [API and SDK](/api-reference/api-reference/credentials/create-credential) supports for credit card management:
+
+**Create a new credit card credential:**
+
+<CodeBlocks>
+```python title="python"
+from skyvern import Skyvern
+skyvern = Skyvern(api_key="your_api_key")
+await skyvern.credentials.create_credential(
+    name="My Credit Card",
+    credential_type="credit_card",
+    credential={
+        "card_number": "4242424242424242",
+        "card_cvv": "424",
+        "card_exp_month": "12",
+        "card_exp_year": "2028",
+        "card_brand": "visa",
+        "card_holder_name": "John Doe",
+    },
+)
+```
+
+```bash title="curl"
+curl -X POST https://api.skyvern.com/v1/credentials \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+      "name": "My Credit Card",
+      "credential_type": "credit_card",
+      "credential": {
+        "card_number": "4242424242424242",
+        "card_cvv": "424",
+        "card_exp_month": "12",
+        "card_exp_year": "2028",
+        "card_brand": "visa",
+        "card_holder_name": "John Doe"
+      }
+    }'
+```
+</CodeBlocks>
+
+**Delete a password credential:**
+
+<CodeBlocks>
+```python title="python"
+from skyvern import Skyvern
+
+skyvern = Skyvern(api_key="your_api_key")
+await skyvern.credentials.delete_credential(credential_id="cred_123456789")
+```
+
+```bash title="curl"
+curl -X POST https://api.skyvern.com/v1/credentials/cred_1234567890/delete \
+	 -H "x-api-key: YOUR_API_KEY"
+```
+</CodeBlocks>

fern/credentials/introduction.mdx

@@ -0,0 +1,61 @@
+---
+title: Secure Credential Management For AI Agents
+subtitle: Never send your credentials to LLMs.
+slug: credentials/introduction
+---
+
+In many scenarios, 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 features, you can manage and use credentials to run agents securely without exposing your credentials to LLMs.
+
+## Credential Support
+<CardGroup cols={2}>
+  <Card
+    title="Password Management"
+    icon="key"
+    href="/credentials/passwords"
+  >
+    Manage and use passwords with Skyvern Agent
+  </Card>
+  <Card
+    title="Credit Cards"
+    icon="credit-card"
+    href="/credentials/credit-cards"
+  >
+    Manage and use credit cards with Skyvern Agent
+  </Card>
+</CardGroup>
+
+## TOTP (2FA/MFA/Verification Code) Support
+
+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 [TOTP (2FA/MFA/Verification Code)](/credentials/totp) for more details.
+
+<CardGroup cols={1}>
+  <Card
+    title="TOTP (2FA/MFA/Verification Code)"
+    icon="pager"
+    href="/credentials/totp"
+  >
+    Manage and use TOTP (2FA/MFA/Verification Code) with Skyvern Agent
+  </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.
+
+See [Bitwarden Integration](/credentials/bitwarden) for more details.
+
+## Coming Soon (Contact Skyvern Support if you need any password integration to help us priroitize)
+
+- 1Password Integration
+- LastPass Integration

fern/credentials/passwords.mdx

@@ -0,0 +1,76 @@
+---
+title: Password Management
+subtitle: How to manage passwords in Skyvern. How Skyvern agent uses passwords.
+slug: credentials/passwords
+---
+
+## Password Management
+
+You can store passwords information in Skyvern. Skyvern agent can use the stored password information to log into a website without sending your username or password to LLMs.
+
+## Manage passwords in Skyvern Cloud
+You can go to [Skyvern's Credentials page](https://app.skyvern.com/credentials) to manage your passwords.
+**Add a new password credential:**
+
+<img src="../images/credential_management/add_password.png" />
+
+Besides the username and password, you can also add the Two Factor Authentication (TOTP) information with the authentication key/secret. If you need to set up TOTP, here are some guides from popular authenticator apps: [Bitwarden](https://bitwarden.com/help/integrated-authenticator/#manually-enter-a-secret), [1Password](https://support.1password.com/one-time-passwords#on-1passwordcom), and [LastPass](https://support.lastpass.com/s/document-item?language=en_US&bundleId=lastpass&topicId=LastPass/create-totp-vault.html&_LANG=enus).
+
+<img src="../images/credential_management/add_password_detail.png" />
+
+**Delete a password credential:**
+
+Click the trash icon and confirm the deletion. If you do this, the password will be deleted from Skyvern PERMANENTLY.
+<img src="../images/credential_management/delete_password.png" />
+
+**Update a password credential:**
+<Warning>Skyvern only allows adding and deleting passwords. If you would like to update a password, you need to delete the existing password and create a new one.</Warning>
+
+## Manage passwords with Skyvern's API or SDK
+We also have [API and SDK](/api-reference/api-reference/credentials/create-credential) supports for password management:
+
+**Create a new password credential:**
+
+<CodeBlocks>
+```python title="python"
+from skyvern import Skyvern
+
+skyvern = Skyvern(api_key="your_api_key")
+await skyvern.credentials.create_credential(
+    name="My Credential",
+    credential_type="password",
+    credential={"username": "username", "password": "password"},
+)
+```
+
+```bash title="curl"
+curl -X POST https://api.skyvern.com/v1/credentials \
+	 -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+	  "name": "My Credential",
+	  "credential_type": "password",
+	  "credential": {
+		"password": "securepassword123",
+		"username": "user@example.com",
+		"totp": "JBSWY3DPEHPK3PXP"
+	  }
+	}'
+```
+</CodeBlocks>
+
+**Delete a password credential:**
+
+<CodeBlocks>
+```python title="python"
+from skyvern import Skyvern
+
+skyvern = Skyvern(api_key="your_api_key")
+await skyvern.credentials.delete_credential(credential_id="cred_123456789")
+```
+
+```bash title="curl"
+curl -X POST https://api.skyvern.com/v1/credentials/cred_1234567890/delete \
+	 -H "x-api-key: YOUR_API_KEY"
+```
+</CodeBlocks>

fern/credentials/totp.mdx

@@ -0,0 +1,134 @@
+---
+title: TOTP (2FA/MFA/Verification Code)
+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: Skyvern gets the code from your endpoint](#option-1-get-code-from-your-endpoint)
+- [Option 2: You push the code to Skyvern](#option-2-push-code-to-skyvern)
+- [Option 3: Store your 2FA/MFA secret in Skyvern's credential management tool](#option-3-store-your-2famfa-secret-in-the-skyvern-credential-tool)
+
+## Option 1: 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:
+
+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
+
+## Option 2: 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 the [TOTP API for more details](https://docs.skyvern.com/api-reference/api-reference/credentials/send-totp-code).
+
+### 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: [`https://api.skyvern.com/api/v1/totp`](https://api.skyvern.com/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 successful, 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>
+
+## Option 3: Store your 2FA/MFA secret in the Skyvern Credential tool
+
+Save your username and password in [Skyvern Credential](https://app.skyvern.com/credentials) where you can also store your 2FA/MFA key/secret.
+
+See [Password Management](/credentials/passwords#manage-passwords-in-skyvern-cloud) for more details.

fern/docs.yml

@@ -74,8 +74,6 @@ navigation:
           path: getting-started/prompting-guide.mdx
     - section: Tasks
       contents:
-        - page: Introduction
-          path: running-tasks/introduction.mdx
         - page: Tasks API
           path: running-tasks/api-spec.mdx
         - api: Endpoints
@@ -102,6 +100,18 @@ navigation:
           path: workflows/workflow-blocks.mdx
         - page: What the heck is a parameter?
           path: workflows/what-is-a-parameter.mdx
+    - section: Credentials
+      contents:
+        - page: Introduction
+          path: credentials/introduction.mdx
+        - page: Password Management
+          path: credentials/passwords.mdx
+        - page: Credit Card Management
+          path: credentials/credit_cards.mdx
+        - page: TOTP (2FA/MFA/Verification Code)
+          path: credentials/totp.mdx
+        - page: Bitwarden
+          path: credentials/bitwarden.mdx
     - section: Integrations
       contents:
         - page: Skyvern MCP

fern/getting-started/quickstart.mdx

@@ -43,6 +43,7 @@ You can also run browser tasks locally in your python code but it takes a bit mo
         task = await skyvern.agent.run_task(prompt="Find the top post on hackernews today")
         print(task)
         ```
+        A local browser will pop up. Skyvern will start executing the task in the browser and close it when the task is done. You will be able to review the task from http://localhost:8080/history
 
 <CardGroup cols={2}>
   <Card

skyvern/forge/sdk/routes/code_samples.py

@@ -362,16 +362,16 @@ CREATE_CREDENTIAL_CODE_SAMPLE = """from skyvern import Skyvern
 
 skyvern = Skyvern(api_key="your_api_key")
 await skyvern.credentials.create_credential(
-    name="Amazon Login",
+    name="My Credential",
     credential_type="password",
-    credential={"username": "user@example.com", "password": "myamazonpassword"},
+    credential={"username": "username", "password": "password"},
 )
 """
 CREATE_CREDENTIAL_CODE_SAMPLE_CREDIT_CARD = """from skyvern import Skyvern
 
 skyvern = Skyvern(api_key="your_api_key")
 await skyvern.credentials.create_credential(
-    name="Amazon Login",
+    name="My Credit Card",
     credential_type="credit_card",
     credential={
         "card_number": "4242424242424242",

skyvern/forge/sdk/routes/credentials.py

@@ -47,7 +47,7 @@ async def parse_totp_code(content: str) -> str | None:
     "/credentials/totp",
     response_model=TOTPCode,
     summary="Send TOTP (2FA, MFA) code to Skyvern",
-    description="Forward a TOTP (2FA, MFA) email or sms message containing the code to Skyvern",
+    description="Forward a TOTP (2FA, MFA) email or sms message containing the code to Skyvern. This endpoint stores the code in database so that Skyvern can use it while running tasks/workflows.",
     tags=["Credentials"],
     openapi_extra={
         "x-fern-sdk-group-name": "credentials",