Skip to main content

​
Login Command

Authenticate with rs-tunnel using your email address: 
rs-tunnel login --email [email protected]
1

Start OAuth Flow

The CLI initiates a Slack OAuth flow and opens your browser automatically:
Waiting for Slack OAuth callback...
If the browser doesn’t open automatically, the CLI displays a URL you can copy and paste.
2

Authorize with Slack

Complete the Slack OAuth authorization in your browser. The server validates:
  • Your email domain matches ALLOWED_EMAIL_DOMAIN
  • Your Slack workspace matches ALLOWED_SLACK_TEAM_ID
3

Login Success

After successful authorization, you’ll see:
Logged in as [email protected]

​
Authentication Flow Details

The authentication process uses:
  • Slack OpenID Connect: Secure OAuth 2.0 flow
  • PKCE: Proof Key for Code Exchange for enhanced security
  • Local callback server: Temporary server to receive OAuth callback
  • JWT tokens: Short-lived access tokens (15 minutes default) with refresh tokens (30 days default)
The CLI never stores your Slack credentials. Only short-lived JWT tokens are saved locally.

​
Access Policy Enforcement

The API server enforces strict access controls:
Only users with email addresses matching the configured domain and belonging to the authorized Slack workspace can authenticate.
Server-side configuration:
  • ALLOWED_EMAIL_DOMAIN: Restricts to specific email domain (e.g., @example.com)
  • ALLOWED_SLACK_TEAM_ID: Restricts to specific Slack workspace

​
Token Storage

Credentials are stored securely using a two-tier approach:

​
Keytar (Preferred)

If the optional keytar dependency is available, credentials are stored in your system’s native credential manager:
  • macOS: Keychain
  • Linux: Secret Service API (libsecret)
  • Windows: Credential Vault

​
Fallback Encryption

If keytar is not available, credentials are encrypted using AES-256-GCM and stored in: 
~/.rs-tunnel/session.enc  # Encrypted session data
~/.rs-tunnel/session.key  # Encryption key (0600 permissions)
For maximum security on supported platforms, install the optional keytar dependency:
npm install -g @ripeseed/rs-tunnel keytar

​
Specifying API Domain

If your organization uses a self-hosted rs-tunnel API, specify the domain during login: 
rs-tunnel login --email [email protected] --domain https://api.your-company.com
The domain is saved to ~/.rs-tunnel/config.json for future commands.
On first run without a configured domain, the CLI will prompt you interactively to enter the API URL.

​
Token Lifecycle

Access Tokens:
  • Valid for 15 minutes (configurable server-side)
  • Automatically refreshed by the CLI when expired
  • Used for all authenticated API requests
Refresh Tokens:
  • Valid for 30 days (configurable server-side)
  • Used to obtain new access tokens
  • Stored securely with access tokens
The CLI handles token refresh automatically. You won’t need to re-authenticate until your refresh token expires (typically 30 days).

​
Troubleshooting Login Issues

​
OAuth State Mismatch

If you see OAuth state mismatch. Aborting login.:
  • Clear your browser cache and cookies for the rs-tunnel domain
  • Try the login flow again
  • Ensure your system clock is synchronized

​
Slack Redirect URI Mismatch

If OAuth fails immediately:
The SLACK_REDIRECT_URI in the API server configuration must exactly match the redirect URI configured in your Slack app settings.

​
Email or Workspace Not Allowed

If authentication is rejected:
  • Verify your email domain matches ALLOWED_EMAIL_DOMAIN
  • Confirm you’re a member of the authorized Slack workspace
  • Contact your administrator to verify server configuration

​
Next Steps

Create Tunnels

Start exposing your local services with rs-tunnel up

Build docs developers (and LLMs) love

Get started for freeTalk to us