User Authentication and MFA

Rexec provides multiple layers of authentication to secure your account and terminal sessions.

Authentication Methods

PipeOps OAuth2 (Recommended)

Rexec uses PipeOps for secure OAuth2 authentication with PKCE (Proof Key for Code Exchange). Sign In Flow:

Click Sign In with PipeOps on the landing page
Authorize Rexec to access your PipeOps account
You’ll be redirected back to Rexec with a session token
Your session includes:
- Access token (JWT) - valid for 1 hour
- Refresh token - for renewing your session
- User profile (name, email, subscription status)

Guest Mode

No sign-in required for quick access:

Instant access - No account needed
Limited resources - Same as free tier (5 containers)
Temporary - 50-hour session limit
No persistence - Sessions expire and cannot be recovered

To use guest mode, simply click Try Without Sign In on the landing page.

OAuth2 Flow Details

PKCE Challenge

Rexec implements OAuth2 with PKCE for enhanced security:

Client generates code verifier - Random 32-byte string
Creates code challenge - SHA256 hash of verifier
Authorization request - Includes challenge
Token exchange - Provides original verifier for validation

This prevents authorization code interception attacks.

Scopes

Rexec requests the following OAuth scopes:

user:read - Access to basic profile information

Token Storage

Tokens are stored in browser localStorage. Clear your browser data to revoke local access.

Security Recommendations:

Use private browsing for shared computers
Sign out when done on public devices
Enable MFA for additional protection

Account-Level MFA

Setting Up TOTP MFA

Navigate to Account → Settings
Find the Multi-Factor Authentication section
Click Enable MFA
Scan the QR code with your authenticator app:
- Google Authenticator
- Authy
- 1Password
- Any TOTP-compatible app
Enter the 6-digit code to confirm setup
Save your backup codes - 10 one-time codes for account recovery

Backup codes are shown only once. Store them securely (password manager, printed copy, etc.).

Logging In with MFA

Once MFA is enabled:

Sign in with PipeOps OAuth as usual
After OAuth completes, you’ll be prompted for a TOTP code
Enter the 6-digit code from your authenticator app
Click Verify to complete login

Using Backup Codes: If you don’t have access to your authenticator:

Click Use a backup code instead
Enter one of your 10 backup codes (format: XXXX-XXXX)
The code will be consumed and removed from the list

Each backup code can only be used once. You’ll have 9 remaining after using one.

Disabling MFA

Navigate to Account → Settings
Scroll to Multi-Factor Authentication
Click Disable MFA
Enter a TOTP code or backup code to confirm
MFA is removed from your account

Terminal-Level MFA Protection

Add an extra layer of security to individual containers or agents.

Enabling Terminal MFA Lock

From the Dashboard:

Find the container or agent you want to protect
Click the ⋮ menu → Lock with MFA
Enter your TOTP code to confirm
The terminal is now MFA-protected (shows 🔒 icon)

Via API:

curl -X POST https://rexec.sh/api/security/terminal/<container-id>/mfa-lock \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Accessing MFA-Locked Terminals

When you try to connect to an MFA-locked terminal:

A modal prompts for your TOTP code
Enter the 6-digit code from your authenticator
Click Verify and Connect
Terminal opens if code is valid

One-time Verification: Each verification is valid for the current terminal session. If you:

Close the terminal
Refresh the page
Open in a new tab

You’ll need to verify again.

Removing Terminal MFA Lock

In the Dashboard, find the locked terminal (🔒 icon)
Click ⋮ → Unlock Terminal
Enter your TOTP code to confirm removal
The terminal is no longer MFA-protected

Via API:

curl -X POST https://rexec.sh/api/security/terminal/<container-id>/mfa-unlock \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

API Authentication

API Tokens

For programmatic access, create long-lived API tokens:

Navigate to Account → API Tokens
Click Generate New Token
Provide details:
- Name: Descriptive label (e.g., “CI/CD Pipeline”)
- Scopes: Select permissions (containers, agents, etc.)
- Expiration: Optional expiry date
Click Create
Copy the token - it won’t be shown again!

Token Format: rexec_<random-string>

Using API Tokens

# Export as environment variable
export REXEC_TOKEN="rexec_your_token_here"

# Use in API requests
curl https://rexec.sh/api/containers \
  -H "Authorization: Bearer $REXEC_TOKEN"

Scopes

Available API token scopes:

agent - Connect and manage agents
containers - Create and manage containers
ssh - Access SSH key management
snippets - Manage command snippets
recordings - Access session recordings

Scope Permissions Table

Scope	Read	Write	Delete
agent	✓	✓	✓
containers	✓	✓	✓
ssh	✓	✓	✓
snippets	✓	✓	✓
recordings	✓	✗	✓

Token Management

List Active Tokens:

curl https://rexec.sh/api/tokens \
  -H "Authorization: Bearer $TOKEN"

Revoke a Token:

curl -X DELETE https://rexec.sh/api/tokens/<token-id> \
  -H "Authorization: Bearer $TOKEN"

Best Practices:

Use separate tokens for different services
Rotate tokens every 90 days
Revoke unused tokens immediately
Never commit tokens to version control

Session Management

Token Refresh

Access tokens expire after 1 hour. Rexec automatically refreshes them using your refresh token. Manual Refresh (API):

curl -X POST https://rexec.sh/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your-refresh-token"}'

Response:

{
  "access_token": "new-jwt-token",
  "expires_in": 3600
}

Session Duration

Free Tier:

OAuth sessions: Until token expires (refresh extends)
Guest sessions: 50 hours maximum
Container lifetime: 50 hours (without subscription)

Pro/Enterprise:

OAuth sessions: Indefinite (with active subscription)
No container time limits

Logging Out

From UI:

Click your profile avatar
Select Sign Out
Session is cleared locally

Programmatic:

curl -X POST https://rexec.sh/api/auth/logout \
  -H "Authorization: Bearer $TOKEN"

This invalidates the current session token.

Security Headers

Rexec sets the following security headers:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Security-Policy: default-src 'self'

WebSocket Authentication

Terminal Connections

WebSocket connections for terminal access support multiple auth methods: 1. Authorization Header:

const ws = new WebSocket('wss://rexec.sh/api/terminal/<id>');
ws.send(JSON.stringify({
  type: 'auth',
  token: 'Bearer your-jwt-token'
}));

2. Query Parameter:

const ws = new WebSocket('wss://rexec.sh/api/terminal/<id>?token=your-jwt-token');

3. Sec-WebSocket-Protocol:

const ws = new WebSocket('wss://rexec.sh/api/terminal/<id>', ['rexec.token.your-jwt-token']);

Method 3 is recommended for browser-based connections to avoid query parameter exposure in logs.

CORS and Origin Validation

Allowed Origins

Rexec validates WebSocket and API origins: Default Allowed:

https://rexec.pipeops.app
https://rexec.pipeops.io
https://rexec.sh
http://localhost:* (development)

Custom Origins: Set ALLOWED_ORIGINS environment variable:

ALLOWED_ORIGINS="https://custom.domain.com,https://another.domain.com"

Blocking Empty Origins

By default, requests without an Origin header are allowed (for CLI/agent clients). To block:

BLOCK_EMPTY_ORIGIN=true

Clients must then send:

curl https://rexec.sh/api/containers \
  -H "Origin: https://rexec.sh" \
  -H "Authorization: Bearer $TOKEN"

Best Practices

Password Security

Rexec uses PipeOps OAuth, so password security is managed by PipeOps:

Use a strong, unique password
Enable MFA on your PipeOps account
Don’t share OAuth tokens
Sign out on shared devices

MFA Recommendations

Enable account MFA for all users
Use terminal MFA for production containers
Print backup codes and store offline
Test backup codes before relying on them
Regenerate backup codes periodically

Token Hygiene

Rotate API tokens every 90 days
Use minimal scopes - only what’s needed
Monitor token usage in Account → API Tokens
Revoke compromised tokens immediately
Use environment variables - never hardcode

Network Security

Always use HTTPS/WSS - no plain HTTP
Verify certificates - don’t ignore TLS warnings
Use VPN for sensitive operations
Avoid public WiFi for critical work

Troubleshooting

OAuth Login Failed

MFA Code Not Accepted

Common Issues:

Time Sync: Ensure device clock is accurate (TOTP requires time sync)

# Check system time
date
# Sync with NTP
sudo ntpdate -s time.nist.gov

Wrong Account: Verify you’re using the correct entry in your authenticator
Backup Codes: Try a backup code if authenticator fails
Rate Limiting: Wait 30 seconds between attempts

Token Expired

If you see “Token expired” errors:

Refresh token - Rexec should auto-refresh
Sign out and back in if refresh fails
Check subscription status - expired Pro users revert to free
Verify time sync - JWT validation is time-sensitive

# Test token validity
curl https://rexec.sh/api/auth/validate \
  -H "Authorization: Bearer $TOKEN"

WebSocket Authentication Failed

Check:

Token format: Should be Bearer <token> or just <token>
Origin header: Must be allowed origin
Token expiry: Refresh if expired
Firewall: Ensure WSS (port 443) is allowed

Debug:

ws.addEventListener('error', (error) => {
  console.log('WebSocket error:', error);
});

ws.addEventListener('close', (event) => {
  console.log('Close code:', event.code);
  console.log('Close reason:', event.reason);
});

Common Close Codes:

1000 - Normal closure
1008 - Policy violation (auth failed)
1011 - Internal error

Advanced: Self-Hosted Auth

If running a self-hosted Rexec instance, configure OAuth:

# .env
PIPEOPS_OAUTH_BASE_URL=https://your-oauth-provider.com
PIPEOPS_CLIENT_ID=your_client_id
PIPEOPS_REDIRECT_URI=https://your-rexec.com/auth/callback
JWT_SECRET=your-256-bit-secret
STRIPE_WEBHOOK_SECRET=whsec_...

See Self-Hosting Guide for complete setup.

Get Started

Core Features

Deployment

User Guides

User Authentication and MFA

User Authentication and MFA

Authentication Methods

PipeOps OAuth2 (Recommended)

Guest Mode

OAuth2 Flow Details

PKCE Challenge

Scopes

Token Storage

Account-Level MFA

Setting Up TOTP MFA

Logging In with MFA

Disabling MFA

Terminal-Level MFA Protection

Enabling Terminal MFA Lock

Accessing MFA-Locked Terminals

Removing Terminal MFA Lock

API Authentication

API Tokens

Using API Tokens

Scopes

Token Management

Session Management

Token Refresh

Session Duration

Logging Out

Security Headers

WebSocket Authentication

Terminal Connections

CORS and Origin Validation

Allowed Origins

Blocking Empty Origins

Best Practices

Troubleshooting

Advanced: Self-Hosted Auth

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment

User Guides

​User Authentication and MFA

​Authentication Methods

​PipeOps OAuth2 (Recommended)

​Guest Mode

​OAuth2 Flow Details

​PKCE Challenge

​Scopes

​Token Storage

​Account-Level MFA

​Setting Up TOTP MFA

​Logging In with MFA

​Disabling MFA

​Terminal-Level MFA Protection

​Enabling Terminal MFA Lock

​Accessing MFA-Locked Terminals

​Removing Terminal MFA Lock

​API Authentication

​API Tokens

​Using API Tokens

​Scopes

​Token Management

​Session Management

​Token Refresh

​Session Duration

​Logging Out

​Security Headers

​WebSocket Authentication

​Terminal Connections

​CORS and Origin Validation

​Allowed Origins

​Blocking Empty Origins

​Best Practices

​Troubleshooting

​Advanced: Self-Hosted Auth

Build docs developers (and LLMs) love

User Authentication and MFA

Authentication Methods

PipeOps OAuth2 (Recommended)

Guest Mode

OAuth2 Flow Details

PKCE Challenge

Scopes

Token Storage

Account-Level MFA

Setting Up TOTP MFA

Logging In with MFA

Disabling MFA

Terminal-Level MFA Protection

Enabling Terminal MFA Lock

Accessing MFA-Locked Terminals

Removing Terminal MFA Lock

API Authentication

API Tokens

Using API Tokens

Scopes

Token Management

Session Management

Token Refresh

Session Duration

Logging Out

Security Headers

WebSocket Authentication

Terminal Connections

CORS and Origin Validation

Allowed Origins

Blocking Empty Origins

Best Practices

Troubleshooting

Advanced: Self-Hosted Auth