Handle 2FA

​

Choose your method

​

Method 1: Store TOTP secret

import os
from skyvern import Skyvern

client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))

credential = await client.create_credential(
    name="Acme Portal Login",
    credential_type="password",
    credential={
        "username": "user@example.com",
        "password": "secure_password",
        "totp": "JBSWY3DPEHPK3PXP",  # Base32 secret from QR code
        "totp_type": "authenticator",
    },
)

​

TOTP types

​

Finding your TOTP secret

1. Go to your account’s security settings
2. Click “Set up authenticator app”
3. Look for “Can’t scan the QR code?” or “Manual entry”
4. Copy the secret key (usually Base32 format like JBSWY3DPEHPK3PXP)

​

Method 2: Push codes to Skyvern

​

Step 1: Set up code forwarding

• Email: Gmail filter + Zapier webhook
• SMS: Twilio webhook to your server
• Email: AWS SES + Lambda function

How to set up Email Forwarding with Zapier?

This setup requires a Zapier Pro plan account.

1

Create a Zapier Zap

1. Go to zapier.com and create a new Zap
2. In the newly created Zap draft, click the “Trigger” button
3. Click Email by Zapier
4. In the Email “Setup”, pick New Inbound Email in the Trigger event selection. Click Continue
5. In Email “Configure”, create an email address which will be used to forward emails for TOTP codes. Click Continue
6. Click the “Action” button and add Webhooks by Zapier
7. In the Setup, choose POST under the Action event selection. Click Continue
8. In the “Configure”, set up these fields to make a POST request to Skyvern’s TOTP API:
   • URL: https://api.skyvern.com/v1/credentials/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
9. Click Continue

2

Add forwarding email and create a filter in Gmail

Go to Gmail Settings → Forwarding and POP/IMAP → click Add a forwarding address → enter the Zapier email address you created. Complete any verification steps.Then go to Filters and Blocked Addresses. Click Create a new filter and set up a filtering rule for your TOTP (2FA/MFA) emails. Click Create filter, check Forward it to, pick the Zapier email address, and update the filter.

3

Test it end to end

Forward any previous TOTP email to the Zapier email address you created.In Zapier, under the “Test” of the Webhooks action, send a request to test it out. If successful, you should see a “A request was sent to Webhooks by Zapier” message.

How to set up SMS Forwarding with Twilio?

Use a virtual phone number service like Twilio or Plivo to receive SMS codes and forward them to Skyvern.

1

Set up a Twilio phone number

Create a Twilio account and provision a phone number. This number will receive the SMS verification codes.

2

Create a Twilio Function to forward codes

In your Twilio console, create a new Function that forwards incoming SMS to Skyvern’s TOTP API:

// Twilio Function
exports.handler = async function(context, event, callback) {
  const axios = require('axios');

  await axios.post('https://api.skyvern.com/v1/credentials/totp', {
    totp_identifier: event.To,  // Your Twilio phone number
    content: event.Body,
    source: 'phone'
  }, {
    headers: {
      'x-api-key': context.SKYVERN_API_KEY,
      'Content-Type': 'application/json'
    }
  });

  return callback(null, new Twilio.Response());
};

Add your SKYVERN_API_KEY as an environment variable in the Twilio Function configuration.

3

Configure the webhook

In your Twilio phone number settings, set the A Message Comes In webhook to point to your Twilio Function URL.

4

Test it

Send a test SMS to your Twilio number and verify the code appears in Skyvern:

curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_TWILIO_NUMBER" \
  -H "x-api-key: $SKYVERN_API_KEY"

​

Step 2: Start the run with a TOTP identifier

result = await client.login(
    credential_type="skyvern",
    url="https://portal.example.com/login",
    credential_id="cred_xyz789",
    totp_identifier="user@example.com",  # Must match when pushing code
)

​

Step 3: Push the code when received

await client.send_totp_code(
    totp_identifier="user@example.com",
    content="Your verification code is 123456",  # Full email/SMS body
    source="email",
)

​

Method 3: Skyvern pulls from your endpoint

​

Step 1: Implement the endpoint

POST https://your-server.com/totp-webhook
x-skyvern-signature: <hmac-sha256-signature>
Content-Type: application/json

{
  "task_id": "tsk_123456"
}

{
  "task_id": "tsk_123456",
  "verification_code": "123456"
}

​

Step 2: Verify request signatures

import hmac
import hashlib

def verify_skyvern_request(request, api_key: str) -> bool:
    signature = request.headers.get("x-skyvern-signature")
    payload = request.body  # bytes

    expected = hmac.new(
        api_key.encode("utf-8"),
        msg=payload,
        digestmod=hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

​

Step 3: Configure the login

result = await client.login(
    credential_type="skyvern",
    url="https://portal.example.com/login",
    credential_id="cred_xyz789",
    totp_url="https://your-server.com/totp-webhook",
)

​

Method 4: Magic links

await client.send_totp_code(
    totp_identifier="user@example.com",
    content="https://portal.example.com/login?token=abc123xyz",
    source="email",
)

1. Trigger the magic link — Navigate to login and enter email
2. Complete login — Use the magic link as the starting URL for the next step

​

Password manager TOTP

​

Bitwarden

1. Open the vault item in Bitwarden
2. Click “Authenticator Key (TOTP)”
3. Enter your TOTP secret or scan the QR code
4. Skyvern retrieves both password and TOTP when using this credential

• Raw secret: JBSWY3DPEHPK3PXP
• otpauth URI: otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example

​

1Password

1. Edit the login item in 1Password
2. Add a “One-Time Password” field
3. Enter the TOTP secret or scan the QR code
4. Reference the item in your Skyvern workflow

​

Multi-field TOTP entry

1. Detects multi-field TOTP layouts
2. Enters the same code across all fields
3. Caches the code to prevent requesting a new one mid-entry

​

Timeouts and polling

​

List recent codes

curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com&limit=10" \
  -H "x-api-key: $SKYVERN_API_KEY"

​

Next steps