Introduction

Prerequisites

This guide assumes you understand Intuned’s core concepts. If you’re new to Intuned, start with the Platform Conceptual Guide first.

The Authentication Challenge

Most valuable web automations require login access, such as:

Automating internal tools
Interacting with SaaS applications
RPA - act on behalf of users
Bypassing bot detection in scraping scenarios
Scraping user-specific data

The challenge: How do you handle authentication efficiently when running browser automations at scale?

Part 1: Core Concepts

AuthSessions: The Foundation

Intuned solves authentication challenges with AuthSessions - reusable browser states that maintain login sessions across multiple Runs. Authentication is deeply integrated into the Run execution model through a dependency system that ensures every API Attempt runs with a valid AuthSession.

Authentication as a Project Feature

Authentication in Intuned can be enabled at the project level. When you enable authentication for a project:

All APIs in that project require AuthSessions
You define authentication logic and APIs once for the entire Project
Every API execution automatically handles AuthSession validation

This architectural decision means:

Consistent authentication behavior across all project APIs
Clear separation between authenticated and non-authenticated projects

How Authentication Changes Your Code

Without authentication, starting a Run is simple. With Authentication enabled in a project, every Run start requires an AuthSession:

*// Without authentication*
runAPI("name-of-api-to-run", { paramName: "param_value" });

*// With authentication*
runAPI("name-of-api-to-run", { paramName: "param_value" }, authSessionId: "auth-session-123");

This single change enables:

Running automations as different users
Reusing login state across different automations
Validating login state is valid on every automation run

Part 2: Authentication Patterns

Before diving into implementation details, understand the two primary usage patterns:

Pattern 1: Service Account (One-to-Many)

When to use: Single account accessing multiple resources

Company Dashboard Account
    └── Create Auth Session (once)
          ├── Scrape Analytics API
          ├── Export Reports API
          └── Update Settings API

Example scenarios:

Internal tools automation: Create one AuthSession with admin credentials, all APIs use the same AuthSession
Authenticated data scraper: Create one AuthSession with a single user account, configure the Job with that AuthSession

Pattern 2: Multi-User Integration (One-to-One)

When to use: Building user-facing automations/integrations

Your App
  ├── User A → Auth Session A → LinkedIn APIs for User A
  ├── User B → Auth Session B → LinkedIn APIs for User B
  └── User C → Auth Session C → LinkedIn APIs for User C

Example scenario:

LinkedIn automation tool: Each user connects their LinkedIn account, creating an AuthSession per user

Part 3: The Authentication Lifecycle

The Dependency Model

Every Attempt Validates First

Unlike traditional approaches where you login once and hope your session is still valid, Intuned validates authentication before EVERY single Attempt.

Run "download-report" (with authSessionId: "session-123", 3 attempts)
│
├── Attempt 1
│   ├── Step 1: AuthSession:Validate Run (Dependency)
│   │   └── Checks if session-123 is still valid (might recreate if expired)
│   └── Step 2: Execute download-report API
│       └── Runs only if validation succeeds
│
├── Attempt 2 (if Attempt 1 failed)
│   ├── Step 1: AuthSession:Validate Run (Dependency)
│   │   └── Checks session-123 again (might recreate if expired)
│   └── Step 2: Execute download-report API
│
└── Attempt 3 (if Attempt 2 failed)
    ├── Step 1: AuthSession:Validate Run (Dependency)
    │   └── Fresh validation check
    └── Step 2: Execute download-report API

Key insight: Each Attempt gets its own fresh validation, ensuring your API never runs with an expired AuthSession.

Understanding Canceled vs Failed

A crucial distinction in Intuned’s dependency model: If AuthSession:Validate fails → The attempt is CANCELED (not failed)

Run "export-data" [Status: Canceled]
└── Attempt 1
    ├── Dependency: AuthSession:Validate ✗ [Failed]
    └── API Execution [Canceled] - Never attempted due to auth failure

This distinction matters:

Failed = The API was executed but encountered an error ( will attempt the API another time)
Canceled = The API was never executed due to unmet dependencies ( no more Attempts will be executed)

Auto-Recreation

How It Works

Auto-recreation keeps your automations running when AuthSessions expire:

You specify auto-recreation when starting a Run:

runAPI({
  api: 'download-report',
  authSession: {
    id: 'auth-session-123',
    autoRecreate: true, *// Defaults to true*
    checkAttempts: 1
  },
})

This parameter flows to the AuthSession:Validate Run

Attempt 1 for "download-report"
└── Dependency: AuthSession:Validate (autoRecreate: true, checkAttempt: 1)
    ├── Check Attempt 1 ✗ (session expired)
    └── Since autoRecreate=true → Trigger recreation...
        ├── Create Attempt 1 ✓ (login succeeded)
    └── Check Attempt 1 ✓ (verify new session works)
└── API Execution for "download-report"

The validation logic (AuthSession:Validate) follows this flow:

AuthSession:Validate Run (autoRecreate: true)
│
├── First: Try check API (with retries)
│   ├── Success → Run Successful, we proceed with API execution
│   └── All retries failed → Go to recreation
│
├── If autoRecreate=true AND check failed:
│   ├── Try create API (with retries)
│   │   ├── Success → Verify with check API
│   │   └── Failed → Validation fails
│   └── Skip if autoRecreate=false
│
└── Final Result:
    ├── Success → Dependency satisfied, run API
    └── Failed → Cancel attempt, mark Run as canceled

Configuration Options (for AuthSession:Validate)

Parameter	Default	Description
`autoRecreate`	`true`	Enable automatic session recreation
`checkAttempts`	`3`	Number of check retry attempts
`createAttempts`	`3`	Number of create retry attempts

Examples

Successful auto-recreation:

*// Your API call*
await runAPI({
  api: 'download-weekly-report',
  authSession: {
    id: 'reporter-session',
    autoRecreate: true,  *// or omitted*
    checkAttempts: 2,
    createAttempts: 2
  }
});

// What happens internally:
Run "download-weekly-report" (autoRecreate: true)
├── Attempt 1
│   ├── AuthSession:Validate (autoRecreate: true)
│   │   ├── Check Attempt 1 [Failed] - Session expired
│   │   ├── Check Attempt 2 [Failed] - Still expired
│   │   ├── Auto-recreation triggered
│   │   ├── Create Attempt 1 [Failed] - loading issue
│   │   ├── Create Attempt 2 [Succeeded] - Logged in
│   │   └── Check Attempt 1 [Succeeded] - New session valid
│   └── API Execution succeeded - Report downloaded
└── Run "download-weekly-report": Success

Without auto-recreation (expired session):

*// Your API call*
await runAPI({
  api: 'download-weekly-report',
  maxAttempts: 2,
  authSession: {
	  id: 'reporter-session',
	  autoRecreate: false,
	  **checkAttempts: 3
	*}*
});

// What happens internally:
Run "download-weekly-report" (autoRecreate: false)
├── Attempt 1
│   ├── AuthSession:Validate (autoRecreate: false)
│   │   ├── Check Attempt 1 [Failed] - Session expired
│   │   ├── Check Attempt 2 [Failed] - Still expired
│   │   └── Check Attempt 3 [Failed] - All retries exhausted
│   └── Attempt canceled - Auth dependency failed
└── Run Status: Canceled (any canceled Attempt canceles the Run)

The Dependency Model: Key Takeaways

Every attempt validates - Fresh auth check for each retry
Failed validation = Canceled attempt - API never runs with bad auth
Auto-recreation is granular - Specified per API call, not globally
Authentication validation (like other AuthSession operations) happen as a Run - AuthSession:Validation
Cancellation bubbles up - Any Attempt canceled = Run canceled

Part 4: AuthSession Types

Overview

Intuned supports three patterns for creating and managing AuthSessions:

Type	Who is authenticating	Auto-Recreation	Credentials Storage	Use Case
Credentials-Based	Automated login	✓ Supported	Stored by Intuned	Everything
Recorder-Based	Human	✗ Not supported	N/A	Complex login
Runtime-Based	Automated login	✓ Required	Not stored	Changing credentials

Credentials-Based

What it is: You provide credentials, Intuned handles AuthSession creation automatically Perfect for:

Standard username/password authentication
API key-based authentication
Any programmatic login flow

How it works:

You implement a create API that performs login with credentials
Intuned captures the browser state after successful login
Supports autoRecreate for automatic renewal

Recorder-Based

What it is: A human logs in manually, Intuned captures the AuthSession Perfect for:

Complex authentication workflows
CAPTCHAs or multi-factor authentication
Biometric/device-based authentication
One-time setup scenarios

How it works:

Human manually logs in through a hosted browser
Intuned captures the authenticated browser state
autoRecreate must be false (requires human intervention)

Runtime-Based

What it is: You provide credentials as part of Run params, authentication happens on-demand Perfect for:

Frequently rotating credentials
When you don’t want Intuned to store credentials
Dynamic credential management

How it works:

Credentials passed as Run parameters
Intuned creates AuthSession as needed
autoRecreate must be true (only way to create session)

Comparison Table

Feature	Credentials-Based	Recorder-Based	Runtime-Based
Setup complexity	Low	Medium	Low
Supports MFA/CAPTCHA	Depends	Yes	No
Credential storage	In Intuned	None	In your system
Auto-recreation	Optional	No	Required
Best for	Most scenarios	Complex auth	Dynamic credentials

Part 5: Advanced Topics

AuthSession Runs Deep Dive

AuthSessions come with special types of Runs that manage authentication operations. Unlike regular API Runs, these can combine different API Attempts in a single Run:

AuthSession:Validate Run

Executed automatically before every authenticated API Attempt. Behavior depends on autoRecreate parameter. Scenario A: Session Valid

AuthSession:Validate Run
└── Check Attempt ✓ → Proceed with API

Scenario B: Session Expired with Auto-Recreation

AuthSession:Validate Run (autoRecreate: true)
├── Check Attempts ✗ (all failed)
├── Create Attempt ✓ (login succeeded)
└── Check Attempt ✓ → Proceed with API

AuthSession:Create Run

Used to create new AuthSessions:

AuthSession:Create Run
├── Create Attempt ✓ (login succeeded)
└── Check Attempt ✓ (verify session)

AuthSession:Update Run

Used to refresh or update existing session credentials:

AuthSession:Update Run
├── Create Attempt ✓ (login with new credentials)
└── Check Attempt ✓ (verify updated session)

Locking and Concurrency

To prevent conflicts, Intuned automatically locks individual AuthSessions during operations that could modify their state. When locks occur:

AuthSession:Create - Creating new session
AuthSession:Update - Updating credentials
AuthSession:Validate (only with autoRecreate: true) - Preventing simultaneous recreations

Lock behavior:

API calls using locked AuthSession → Rejected immediately
Scheduled Job Runs using locked AuthSession → Canceled with reason
Locks are per-AuthSession (parallel operations on different AuthSessions work fine)

Jobs and Authentication

Jobs in authenticated projects have special handling for AuthSessions to ensure reliable execution at scale. In an authenticated Project:

Every Job must specify an authSessionId
All Runs within the JobRun use this same AuthSession
The autoRecreate parameter is configured at the Job level

AuthSession Validation

Jobs implement a two-tier validation approach:

Job-Level Validation (Once per JobRun): When a JobRun starts, it performs initial validation and handles the AuthSession lifecycle
Run-Level Validation (Before each Attempt) Each Run within the JobRun still validates before every Attempt

Job Run Started
├── Initial AuthSession:Validate ✓ (Job level)
│   └── Recreate if needed
├── Run 1
│   └── Attempt 1
│       ├── AuthSession:Validate (Run level)
│       │   └── Recreate if needed (at the JobRun level)
│       └── Execute API
├── Run 2
│   └── Attempt 1
│       ├── AuthSession:Validate (Run level)
│       │   └── Recreate if needed (at the JobRun level)
│       └── Execute API
└── ... more runs
│ 
└── Release lock when JobRun is complete

Auto-Recreation Behavior

When autoRecreate: true and an AuthSession expires:

Recreation happens at the Job level, not per Run
The JobRun can recreate the session multiple times if needed during execution
All subsequent Runs automatically use the recreated session

Benefits:

No race conditions: Single point of recreation prevents conflicts
Efficiency: One recreation serves all remaining Runs
Reliability: Every Run executes with a valid AuthSession

Proxy Support

Each AuthSession can be configured with its own proxy:

Geographic-specific authentication
IP rotation strategies
Bypassing regional restrictions

Key behavior:

Proxy permanently tied to AuthSession
Every Run using AuthSession uses its proxy
To change proxy, update the AuthSession

Quick Reference

Key Concepts Checklist

Every attempt validates auth first
Failed validation = Canceled (not Failed)
autoRecreate defaults to true
Locks are per-AuthSession, not global
AuthSession type determines recreation support
Jobs handle auth at multiple levels
Proxies are tied to AuthSessions

Common Scenarios

Scenario	Solution
Simple scraper with login	Credentials-based + Service Account pattern
User-facing integration	Multi-User pattern with appropriate type
Complex MFA login	Recorder-based AuthSession
Geographic restrictions	AuthSession with proxy configuration

Summary

Intuned’s authentication system provides:

Automatic Validation - Every attempt validates auth first
Smart Recovery - Auto-recreation keeps automations running
Flexible Methods - Support for any authentication type
Complete Visibility - Full audit trail of all auth operations
Graceful Failure Handling - Canceled attempts prevent running with bad auth
Conflict Prevention - Per-AuthSession locking ensures consistent state
Efficient Job Execution - Jobs handle auth at multiple levels

Key architectural insights:

Authentication is a project-level feature
Dependency model ensures auth validity
Auto-recreation is controlled per Run/Job
Different AuthSession types for different needs

Next Steps

Implementation Guide → Building Your First Authenticated Automation
API Reference → Authentication API Documentation
Troubleshooting → Common Authentication Issues

Getting started

Guides

Platform

Data extraction

Actions

Authentication sessions

Support

​Introduction

​Prerequisites

​The Authentication Challenge

​Part 1: Core Concepts

​AuthSessions: The Foundation

​Authentication as a Project Feature

​How Authentication Changes Your Code

​Part 2: Authentication Patterns

​Pattern 1: Service Account (One-to-Many)

​Pattern 2: Multi-User Integration (One-to-One)

​Part 3: The Authentication Lifecycle

​The Dependency Model

​Every Attempt Validates First

​Understanding Canceled vs Failed

​Auto-Recreation

​How It Works

​Configuration Options (for AuthSession:Validate)

​Examples

​The Dependency Model: Key Takeaways

​Part 4: AuthSession Types

​Overview

​Credentials-Based

​Recorder-Based

​Runtime-Based

​Comparison Table

​Part 5: Advanced Topics

​AuthSession Runs Deep Dive

​AuthSession:Validate Run

​AuthSession:Create Run

​AuthSession:Update Run

​Locking and Concurrency

​Jobs and Authentication

​AuthSession Validation

​Auto-Recreation Behavior

​Proxy Support

​Quick Reference

​Key Concepts Checklist

​Common Scenarios

​Summary

​Next Steps

Introduction

Prerequisites

The Authentication Challenge

Part 1: Core Concepts

AuthSessions: The Foundation

Authentication as a Project Feature

How Authentication Changes Your Code

Part 2: Authentication Patterns

Pattern 1: Service Account (One-to-Many)

Pattern 2: Multi-User Integration (One-to-One)

Part 3: The Authentication Lifecycle

The Dependency Model

Every Attempt Validates First

Understanding Canceled vs Failed

Auto-Recreation

How It Works

Configuration Options (for AuthSession:Validate)

Examples

The Dependency Model: Key Takeaways

Part 4: AuthSession Types

Overview

Credentials-Based

Recorder-Based

Runtime-Based

Comparison Table

Part 5: Advanced Topics

AuthSession Runs Deep Dive

AuthSession:Validate Run

AuthSession:Create Run

AuthSession:Update Run

Locking and Concurrency

Jobs and Authentication

AuthSession Validation

Auto-Recreation Behavior

Proxy Support

Quick Reference

Key Concepts Checklist

Common Scenarios

Summary

Next Steps