iFlow Authentication

Overview

iFlow authentication provides access to iFlow’s AI services through two methods:

OAuth 2.0 Flow - Standard OAuth authentication with browser
Cookie Authentication - Direct authentication using browser cookies

Both methods require an email address for account identification and token file naming.

Prerequisites

Before authenticating with iFlow, ensure you have:

An iFlow account with API access
CLIProxyAPI server installed and configured
Email address associated with your iFlow account
For OAuth: A web browser
For cookie auth: Browser cookies from an active iFlow session

Authentication Method 1: OAuth Flow

The OAuth flow provides standard browser-based authentication.

Start OAuth login

Run the following command:

./CLIProxyAPI -iflow-login

This will:

Start a local OAuth callback server
Open your default web browser
Navigate to iFlow’s OAuth authorization page

Complete authorization

In the browser:

Sign in to your iFlow account
Review the requested permissions
Click “Authorize” to grant access
Wait for automatic redirect to callback

Provide email address

When prompted, enter your iFlow account email:

Enter your email address:
[email protected]

This email is required for account identification.

Confirmation

After successful authorization:

Authentication saved to /path/to/auth/iflow-<email>-<timestamp>.json
iFlow authentication successful!

OAuth Flow Options

Manual Browser Mode

For headless servers or when the browser doesn’t open:

./CLIProxyAPI -iflow-login -no-browser

The CLI displays the authorization URL for manual opening.

Custom Callback Port

./CLIProxyAPI -iflow-login -oauth-callback-port 9000

iFlow OAuth authentication requires an email address. If you don’t provide one when prompted, authentication will fail with an “EmailRequiredError”.

Cookie authentication allows you to use existing browser session cookies for quick setup.

Get iFlow cookies from browser

Open your browser and sign in to iFlow. Then extract cookies:Chrome/Edge:

Open DevTools (F12)
Go to Application → Cookies
Find iFlow’s domain
Copy all cookie values

Firefox:

Open DevTools (F12)
Go to Storage → Cookies
Find iFlow’s domain
Copy cookie values

Look for important cookies like:

BXAuth or similar session identifiers
Authentication tokens
Session IDs

Start cookie authentication

Run the cookie authentication command:

./CLIProxyAPI -iflow-cookie

Paste cookies

When prompted, paste your cookies:

Enter iFlow Cookie (from browser cookies):
BXAuth=value1; SessionID=value2; Token=value3

The CLI automatically:

Normalizes cookie format
Extracts BXAuth identifier
Validates cookie structure

Check for duplicates

The CLI checks if this BXAuth already exists:

If duplicate found: Authentication is skipped
If unique: Proceeds with authentication

Duplicate BXAuth found, authentication already exists: [email protected]

Authenticate and save

If cookies are valid, the CLI:

Authenticates with iFlow servers
Retrieves API key and expiration
Saves token to auth directory

Authentication successful! API key: iflow-key-xxxxx
Expires at: 2026-12-31T23:59:59Z
Authentication saved to: /path/to/auth/[email protected]

Cookie authentication requires active browser cookies. Cookies expire when:

You sign out of iFlow
The session timeout is reached
Cookies are cleared from your browser

You’ll need to re-authenticate when cookies expire.

Feature	OAuth Flow	Cookie Authentication
Browser required	Yes (OAuth flow)	Yes (to get cookies)
Setup speed	Moderate	Fast
Expiration handling	Automatic refresh	Manual re-auth needed
Security	OAuth 2.0 standard	Depends on cookie security
Best for	Long-term use	Quick testing/setup
Duplicate detection	No	Yes (by BXAuth)

Recommendation:

Use OAuth flow (-iflow-login) for production and long-term usage
Use cookie auth (-iflow-cookie) for quick testing or when OAuth isn’t working

Configuration

Token Storage Location

Authentication tokens are stored in the configured auth directory:

Default location: Set via -auth-dir or in config file
Filename format: iflow-<email>-<timestamp>.json
Example: [email protected]

Token Contents

OAuth tokens contain:

OAuth 2.0 access token
Refresh token (if provided)
Token expiration
Email address
Authentication metadata

Cookie tokens contain:

API key extracted from session
BXAuth identifier
Cookie expiration
Email address
Original cookie values (normalized)

Email Address Requirements

The email address you provide:

Must match your iFlow account email
Is required for both OAuth and cookie authentication
Is used for token file naming and organization
Identifies your account in logs and monitoring

Multiple Accounts

Authenticate with multiple iFlow accounts for increased capacity:

# OAuth method - Account 1
./CLIProxyAPI -iflow-login

# Cookie method - Account 2
./CLIProxyAPI -iflow-cookie

# OAuth method - Account 3
./CLIProxyAPI -iflow-login

Each account:

Creates a separate token file
Has its own API key/tokens
Is automatically loaded by the server
Participates in credential rotation

Verification

To verify your authentication is working:

Check token file exists

ls -la /path/to/auth-dir/iflow-*.json

You should see your iFlow token file(s).

Verify token contents

For cookie authentication, check the API key was saved:

cat /path/to/auth-dir/iflow-*.json | grep -o '"api_key":"[^"]*"'

Start the server

./CLIProxyAPI

Watch for log messages indicating iFlow credentials were loaded.

Make a test request

Test iFlow access:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "iflow-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Troubleshooting

OAuth Flow Issues

Email required error

Cause: No email address provided when prompted. Solution:

Run the login command again
Enter your iFlow account email when prompted
Complete the OAuth flow

Browser doesn’t open

Solution: Use manual browser mode:

./CLIProxyAPI -iflow-login -no-browser

OAuth timeout

Cause: Authorization not completed quickly enough. Solution:

Complete OAuth flow faster
Check firewall settings
Verify callback port is accessible

Cause: Cookies not properly formatted. Solution:

Ensure cookies are in name=value; name2=value2 format
Copy all relevant cookies from browser
Don’t modify cookie values manually
Check for line breaks or extra spaces

Cause: Cookie string couldn’t be parsed. Solution:

# Correct format (semicolon-separated)
BXAuth=abc123; SessionID=xyz789; Token=token123

# Incorrect formats to avoid
BXAuth: abc123\nSessionID: xyz789  # Wrong: using colons and newlines
{"BXAuth":"abc123"}  # Wrong: JSON format

Duplicate BXAuth detected

Cause: This BXAuth identifier already exists in your auth directory. Solution:

This is actually helpful - it prevents duplicate credentials
If you want to refresh: delete the existing file first
If using a different account: get cookies from that account’s session

# Remove duplicate if you want to re-authenticate
rm /path/to/auth-dir/[email protected]*.json
./CLIProxyAPI -iflow-cookie

Possible causes:

Cookies expired
Invalid or incomplete cookies
Not signed in to iFlow in browser
Network connectivity issues

Solution:

Sign in to iFlow in your browser
Get fresh cookies immediately
Paste cookies into CLI promptly
Ensure no line breaks or formatting issues

API key not returned

Cause: iFlow servers didn’t return an API key. Solution:

Verify your account has API access
Check if cookies are still valid
Sign in to iFlow web interface to refresh session
Contact iFlow support if issue persists

Common Issues (Both Methods)

Token not saving

Cause: Permission issues with auth directory. Solution:

mkdir -p /path/to/auth-dir
chmod 755 /path/to/auth-dir

Email format invalid

Cause: Email address format is incorrect. Solution:

Must be valid email format: [email protected]
No spaces or special characters except @, ., +, -, _
Must match your actual iFlow account email

Security Considerations

OAuth Authentication Security

Uses standard OAuth 2.0 protocols
Tokens are refreshed automatically
Refresh tokens enable long-term access
Revocable through iFlow account settings

Less secure than OAuth - cookies can be intercepted
No automatic refresh - manual re-auth needed when expired
BXAuth is sensitive - treat like a password
Duplicate detection prevents accidental credential duplication

Cookie Security Best Practices:

Never share cookies publicly or commit to version control
Get cookies from HTTPS connections only
Don’t paste cookies in untrusted terminals
Delete cookies after copying from browser DevTools
Use OAuth flow for production environments

Token File Security

Both methods store sensitive credentials:

Files use 0600 permissions (owner-only read/write)
Auth directory should be 755 (rwxr-xr-x)
Never commit token files to git
Include auth directory in .gitignore
Back up securely if needed

Token Expiration and Refresh

OAuth Tokens

Automatically refreshed by the server
Refresh tokens enable seamless renewal
No manual intervention required
Check logs for refresh failures

Not automatically refreshed
Expire when browser session expires
Require manual re-authentication
Expiration date shown during authentication

# Check expiration in token file
cat /path/to/auth-dir/iflow-*.json | grep expire

When cookie tokens expire:

Delete the expired token file
Get fresh cookies from browser
Run -iflow-cookie again

Re-authentication

Re-authenticate OAuth

# Remove old token
rm /path/to/auth-dir/[email protected]*.json

# Run OAuth login
./CLIProxyAPI -iflow-login

# Remove old token
rm /path/to/auth-dir/[email protected]*.json

# Get fresh cookies from browser
# Run cookie authentication
./CLIProxyAPI -iflow-cookie

Set a reminder to re-authenticate before cookie expiration if you’re using cookie authentication for important services.

Best Practices

Choose the right method:
- Production: Use OAuth flow
- Testing: Cookie auth is acceptable
- Long-term: OAuth provides automatic refresh
Email management:
- Use the correct email for your iFlow account
- Different emails for different accounts
- Email in filename helps identify credentials
Cookie handling:
- Get cookies from secure HTTPS sessions only
- Copy immediately after signing in
- Delete from browser DevTools after copying
- Don’t store cookies in plaintext elsewhere
Multiple accounts:
- Mix OAuth and cookie methods if needed
- Each account needs unique email
- Server handles credential rotation automatically
Security:
- Protect token files like passwords
- Use appropriate file permissions
- Monitor auth directory for unauthorized access
- Re-authenticate if tokens may be compromised

Get Started

Core Concepts

Configuration

OAuth Authentication

Integrations

Deployment

Overview

Prerequisites

Authentication Method 1: OAuth Flow

OAuth Flow Options

Manual Browser Mode

Custom Callback Port

Configuration

Token Storage Location

Token Contents

Email Address Requirements

Multiple Accounts

Verification

Troubleshooting

OAuth Flow Issues

Email required error

Browser doesn’t open

OAuth timeout

Duplicate BXAuth detected

API key not returned

Common Issues (Both Methods)

Token not saving

Email format invalid

Security Considerations

OAuth Authentication Security

Token File Security

Token Expiration and Refresh

OAuth Tokens

Re-authentication

Re-authenticate OAuth

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

OAuth Authentication

Integrations

Deployment

​Overview

​Prerequisites

​Authentication Method 1: OAuth Flow

​OAuth Flow Options

​Manual Browser Mode

​Custom Callback Port

​Authentication Method 2: Cookie Authentication

​Comparison: OAuth vs Cookie Authentication

​Configuration

​Token Storage Location

​Token Contents

​Email Address Requirements

​Multiple Accounts

​Verification

​Troubleshooting

​OAuth Flow Issues

​Email required error

​Browser doesn’t open

​OAuth timeout

​Cookie Authentication Issues

​Invalid cookie format

​Cookie normalization failed

​Duplicate BXAuth detected

​Cookie authentication failed

​API key not returned

​Common Issues (Both Methods)

​Token not saving

​Email format invalid

​Security Considerations

​OAuth Authentication Security

​Cookie Authentication Security

​Token File Security

​Token Expiration and Refresh

​OAuth Tokens

​Cookie Tokens

​Re-authentication

​Re-authenticate OAuth

​Re-authenticate Cookie

​Best Practices

​Related Resources

Build docs developers (and LLMs) love

Overview

Prerequisites

Authentication Method 1: OAuth Flow

OAuth Flow Options

Manual Browser Mode

Custom Callback Port

Authentication Method 2: Cookie Authentication

Comparison: OAuth vs Cookie Authentication

Configuration

Token Storage Location

Token Contents

Email Address Requirements

Multiple Accounts

Verification

Troubleshooting

OAuth Flow Issues

Email required error

Browser doesn’t open

OAuth timeout

Cookie Authentication Issues

Invalid cookie format

Cookie normalization failed

Duplicate BXAuth detected

Cookie authentication failed

API key not returned

Common Issues (Both Methods)

Token not saving

Email format invalid

Security Considerations

OAuth Authentication Security

Cookie Authentication Security

Token File Security

Token Expiration and Refresh

OAuth Tokens

Cookie Tokens

Re-authentication

Re-authenticate OAuth

Re-authenticate Cookie

Best Practices

Related Resources