Two-Factor Authentication

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

Supported 2FA Channels

Channel	Typical Form	Notes
Authenticator App	Time‑based (TOTP) 6‑digit codes generated from a shared secret.	Most secure and our preferred method when you can access the secret.
SMS	One‑time code delivered by text message.	Requires a phone number on record with the service you automate.
Email	One‑time code delivered to a mailbox.	Requires an email address on record with the service you automate.
Magic Link	Login link delivered to a mailbox.	Uses the same CloudCruise email setup as email 2FA.

Integration Patterns

1. Vault‑Stored Authenticator Secret (Recommended)

When you can export or reveal the QR‑code secret behind a TOTP 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 / Magic Link)

CloudCruise can provide an isolated phone number and inbox per Vault credential. Perform a one‑time change in the target account:

Replace the existing 2FA phone number or email with the CloudCruise‑supplied value.
(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 or magic-link 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

Pros	Cons
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.
Supports email codes and magic links.	Magic-link workflows need a TFA node configured for `MAGIC_LINK`.

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:

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"
}

Your application notifies the user and collects the 6‑digit code.
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

Pros	Cons
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

Scenario	Best 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
The service sends email login links instead of numeric codes.	CC 2FA Proxy with `MAGIC_LINK`
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.

Getting Started

Concepts

API Reference

SDK

Integrations

Two-Factor Authentication

Supported 2FA Channels

Integration Patterns

1. Vault‑Stored Authenticator Secret (Recommended)

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

Pros / Cons

3. User‑Driven Code Submission (Minimal Setup)

Pros / Cons

Choosing an Approach

Error Handling & Timeouts

Security Considerations

​Supported 2FA Channels

​Integration Patterns

​1. Vault‑Stored Authenticator Secret (Recommended)

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

​Pros / Cons

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

​Pros / Cons

​Choosing an Approach

​Error Handling & Timeouts

​Security Considerations

Supported 2FA Channels

Integration Patterns

1. Vault‑Stored Authenticator Secret (Recommended)

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

Pros / Cons

3. User‑Driven Code Submission (Minimal Setup)

Pros / Cons

Choosing an Approach

Error Handling & Timeouts

Security Considerations