Auth & Users

Authentication Configuration

R2R provides a flexible authentication system that supports both server-side configuration and runtime customization. The authentication system manages user registration, login, session management, and access control.

Server Configuration

The authentication settings can be configured in your r2r.toml file under the auth section:

1
[auth]
2
provider = "r2r"  # currently only "r2r" | "supabase" are supported
3
require_authentication = false  # set to true to enforce authentication
4
require_email_verification = false  # set to true to require email verification
5
default_admin_email = "[email protected]"
6
default_admin_password = "change_me_immediately"
7
access_token_lifetime_in_minutes = 3600  # 60 hours
8
refresh_token_lifetime_in_days = 7  # 7 days
9
secret_key = "your-secret-key"  # Used for JWT token signing

Environment Variables

You can also configure authentication using environment variables:

$
export R2R_SECRET_KEY=your-secret-key
>
export R2R_ACCESS_LIFE_IN_MINUTES=3600
>
export R2R_REFRESH_LIFE_IN_MINUTES=10080  # 7 days in minutes

Key Features

1. User Management

• User registration with optional email verification
• Password hashing and security
• Linking of ingested documents to user
• Assignment of document collections to / from user
• User roles (superuser/admin and regular users)

2. Token Management

• JWT-based authentication
• Access and refresh token system
• Configurable token lifetimes
• Token blacklisting for logout

3. Security Features

• Password reset functionality
• Email verification (optional)
• Token expiration and refresh
• Password change capabilities

API Methods

The authentication system provides several key endpoints:

1. Registration:

1
from r2r import R2RClient
2
3
client = R2RClient()
4
response = await client.users.register(
5
    email="[email protected]",
6
    password="secure_password"
7
)

2. Login:

1
await client.users.login(
2
    email="[email protected]",
3
    password="secure_password"
4
)
5
# caches access_token and refresh_token

3. Token Refresh:

1
await client.users.refresh_access_token(refresh_token)

4. Logout:

1
await client.users.logout()

Refer directly to the Users API Reference for more details.

Email Configuration

If email verification is enabled, you’ll need to configure an email provider:

1
[email]
2
provider = "smtp"  # or other supported email providers
3
smtp_host = "smtp.example.com"
4
smtp_port = 587
5
smtp_username = "your_username"
6
smtp_password = "your_password"
7
from_email = "[email protected]"

Cryptography Configuration

R2R is designed to support arbitrary crypotgraphy providers through the r2r.toml:

1
[crypto]
2
provider = "bcrypt" # currently only "bcrypt" supported

Protected Endpoints

When authentication is enabled (require_authentication = true), all secure R2R endpoints require a valid access token. The user’s access token will automatically be included in API calls after login:

1
client = R2RClient(
2
    base_url="http://localhost:7272",
3
    auth_token=access_token
4
)
5
client.users.login(...)
6
7
# All subsequent calls will include the token
8
response = client.retrieval.rag("What is authentication?")

Error Handling

The authentication system provides detailed error messages for common scenarios:

• Invalid credentials
• Expired tokens
• Unauthorized access
• Email verification required
• Invalid reset tokens

Example error handling:

1
from r2r import R2RException
2
3
try:
4
    await client.users.login(email="[email protected]", password="wrong_password")
5
except R2RException as e:
6
    if e.status_code == 401:
7
        print("Invalid credentials")
8
    elif e.status_code == 400:
9
        print("Email not verified")