Skip to main content
Browser agents frequently encounter login flows secured by two‑factor authentication (2FA). CloudCruise supports three common 2FA channels and offers two integration patterns so you can choose the right balance of autonomy vs. human oversight.

​
Supported 2FA Channels

ChannelTypical FormNotes
Authenticator AppTime‑based (TOTP) or counter‑based (HOTP) 6‑digit codes generated from a shared secret.Most secure and our preferred method when you can access the secret.
SMSOne‑time code delivered by text message.Requires a phone number on record with the service you automate.
EmailOne‑time code delivered to a mailbox.Requires an email address on record with the service you automate.

​
Integration Patterns

When you can export or reveal the QR‑code secret behind a TOTP/HOTP authenticator, simply store that secret in the Vault entry that belongs to the credential set: 
{
  "username": "alice@example.com",
  "password": "••••••••",
  "tfa_secret": "JBSWY3DPEHPK3PXP"
}
You can do this with our /vault endpoints or using our UI here. At runtime the browser agent generates the current code itself, allowing fully autonomous logins with no external dependency.
Tip – This approach also works for SMS or email 2FA when the underlying service lets you switch to an authenticator‑app factor.

​
2. CC 2FA Proxy (Hands‑Off SMS / Email)

CloudCruise can provide an isolated phone number and inbox per Vault credential. Perform a one‑time change in the target account:
  1. Replace the existing 2FA phone number or email with the CloudCruise‑supplied value.
  2. (Optional) Add a forwarding rule so codes are copied to a human‑accessible destination.
Alternative: Instead of changing the registered email, you can configure your existing inbox to forward 2FA emails to the vault entry email address. At run‑time the flow looks like this: 
Service  →  sends code  →  CC Proxy  →  Browser Agent
No webhooks or manual steps are needed; agents consume the code automatically.

​
Pros / Cons

ProsCons
Zero delay — agent stays autonomous.One‑time account update required.
Dedicated channel per credential — no collision between tenants.Forwarding rule needed if humans still log in.

​
3. User‑Driven Code Submission (Minimal Setup)

If you cannot change the registered phone/email or export the authenticator secret, fall back to interactive mode:
  1. Agent reaches the 2FA prompt and emits a webhook:
{
    "payload": {
        "current_step": "Enter 2FA Code",
        "missing_properties": ["code"],
        "message": "Please enter the 6-digit code sent to your phone",
        "session_id": "session-123",
        "workflow_id": "workflow-456",
        "expected_json_schema_datamodel": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "string",
                    "pattern": "^\\d{6}$",
                    "description": "6-digit verification code"
                }
            },
            "required": ["code"]
        }
    },
    "timestamp": 1710936000,
    "expires_at": 1710936300,
    "event": "interaction.waiting"
}
  1. Your application notifies the user and collects the 6‑digit code.
  2. Submit the code via the User Interaction API:
curl -X POST \
  -H "cc-key: $CC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}' \
  https://api.cloudcruise.com/run/{session_id}/user_interaction

​
Pros / Cons

ProsCons
No changes to the service’s 2FA configuration.Requires user attention within ~5 minutes (default expiry).
Works with any factor type.Potential overnight downtime if sessions expire unattended.

​
Choosing an Approach

ScenarioBest fit
You control the account and can export the seed.Vault‑Stored Secret
Shared team account; you want agents + humans to log in.CC 2FA Proxy with forwarding
Highly regulated service that forbids factor changes.User‑Driven Submission

​
Error Handling & Timeouts

  • A 2FA code must be delivered to the agent within 5 minutes of the prompt.
  • If the window elapses, the run fails; retry or re‑schedule as needed.

​
Security Considerations

  • All codes received via the CC 2FA Proxy are discarded after use.
  • When you store a TOTP secret in the Vault, it is wrapped with the same envelope‑encryption scheme used for passwords.
  • Webhook payloads never contain raw codes—only metadata indicating that a code is required.