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
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
- 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:- 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- 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- 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.Understanding Canceled vs Failed
A crucial distinction in Intuned’s dependency model: If AuthSession:Validate fails → The attempt is CANCELED (not failed)- 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:
- This parameter flows to the AuthSession:Validate Run
- The validation logic (AuthSession:Validate) follows this flow:
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: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
- 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
- Human manually logs in through a hosted browser
- Intuned captures the authenticated browser state
autoRecreate
must befalse
(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
- Credentials passed as Run parameters
- Intuned creates AuthSession as needed
autoRecreate
must betrue
(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 onautoRecreate
parameter.
Scenario A: Session Valid
AuthSession:Create Run
Used to create new AuthSessions:AuthSession:Update Run
Used to refresh or update existing session credentials: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
- 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
Auto-Recreation Behavior
WhenautoRecreate: 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
- 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
- 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 totrue
- 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
- 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