Quick Links

/docs/cli-flags/docs/troubleshooting/docs/webhooks/solutions/docs/referrals

Answer-first summary

Where should I start in InstaTunnel docs?

Follow this order: Install CLI, authenticate, run first tunnel, then move to MCP/webhooks/referrals based on your use case. Use CLI Flags and Troubleshooting for day-to-day operations.

Last reviewed: March 5, 2026
Compatibility: Core docs align with CLI v1 default and MCP --transport v2 for streaming clients.

Quick command

instatunnel auth login -e you@example.com && instatunnel 3000 --subdomain docs-demo

Common failures and quick fixes

  • Auth not persisted-Run instatunnel auth set-key it_your_api_key to store your key locally.
  • Webhook 401 signature errors-Use provider-specific secret verification guides in /docs/webhooks before production tests.

Evidence and trust

Use these references when evaluating compatibility, reliability, and security posture.

Release cadence

CLI and docs release notes are updated continuously, with version-specific compatibility notes.

View release notes

Security controls

Review policy enforcement, auth layers, and operational safeguards in the security whitepaper.

Open security whitepaper

Reliability runbooks

Troubleshooting guides cover common failures, recovery steps, and CLI compatibility baselines.

Read troubleshooting guides

Documentation

Authentication

Authenticate and manage API access with comprehensive authentication endpoints for secure tunnel management.

🔑 API Authentication

API Key Authentication

# All API requests require authentication
Authorization: Bearer YOUR_API_KEY
# Example API request
curl -H "Authorization: Bearer it_1234567890abcdef" \
  https://api.instatunnel.my/v1/tunnels

API Key Format: All InstaTunnel API keys start with it_ followed by 16 characters.

Get API Key

# Login via CLI to get API key
$ instatunnel login
📧 Email: user@example.com
🔒 Password: ********
✅ Login successful
🔑 API Key: it_1234567890abcdef
# View current API key
$ instatunnel auth status
Current API Key: it_***...def
Status: Valid
Expires: Never

👤 User Management

GET /auth/user

Get current user information.

# Get user info
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.instatunnel.my/v1/auth/user
// Response
{
  "id": "user_456",
  "email": "user@example.com",
  "name": "John Doe",
  "plan": "pro",
  "created_at": "2024-01-15T10:30:00Z",
  "usage": {
    "tunnels_created": 156,
    "data_transferred": "2.4 GB",
    "requests_served": 12487
  }
}

POST /auth/login

Authenticate with email and password to get API key.

# Login with credentials
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"mypassword"}' \
  https://api.instatunnel.my/v1/auth/login
// Response
{
  "api_key": "it_1234567890abcdef",
  "user": {
    "id": "user_456",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

POST /auth/logout

Invalidate current API key.

# Logout and invalidate API key
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.instatunnel.my/v1/auth/logout

🔐 API Key Management

GET /auth/keys

List all API keys for your account.

# List API keys
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.instatunnel.my/v1/auth/keys
// Response
{
  "keys": [
    {
      "id": "key_123",
      "name": "Production Key",
      "key": "it_***...def",
      "created_at": "2024-01-15T10:30:00Z",
      "last_used": "2024-07-02T14:30:00Z",
      "permissions": ["tunnels:read", "tunnels:write"]
    }
  ]
}

POST /auth/keys

Create a new API key with specific permissions.

# Create new API key
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI/CD Key","permissions":["tunnels:read"]}' \
  https://api.instatunnel.my/v1/auth/keys
// Available permissions
[
  "tunnels:read", // View tunnels
  "tunnels:write", // Create/modify tunnels
  "tunnels:delete", // Delete tunnels
  "analytics:read", // View analytics
  "admin:read", // Admin read access
  "admin:write" // Admin write access
]

DELETE /auth/keys/:id

Revoke an API key.

# Revoke API key
curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.instatunnel.my/v1/auth/keys/key_123

🛡️ OAuth Integration

OAuth Flow

1. Authorization URL
# Redirect user to authorization URL
https://api.instatunnel.my/v1/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=tunnels:read,tunnels:write&
  state=random_state_string
2. Exchange Code for Token
# Exchange authorization code for access token
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "code":"AUTH_CODE",
    "grant_type":"authorization_code"
  }' \
  https://api.instatunnel.my/v1/oauth/token

Token Refresh

# Refresh access token
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "refresh_token":"REFRESH_TOKEN",
    "grant_type":"refresh_token"
  }' \
  https://api.instatunnel.my/v1/oauth/token

⚙️ Permission Scopes

Available Scopes

Tunnel Management
  • • tunnels:read - View tunnel information
  • • tunnels:write - Create and modify tunnels
  • • tunnels:delete - Delete tunnels
  • • tunnels:stats - Access tunnel statistics
Analytics & Monitoring
  • • analytics:read - View analytics data
  • • logs:read - Access request logs
  • • alerts:read - View alerts configuration
  • • alerts:write - Configure alerts
Account Management
  • • account:read - View account information
  • • account:write - Modify account settings
  • • billing:read - View billing information
  • • keys:manage - Manage API keys
Administration
  • • admin:read - Admin read access
  • • admin:write - Admin write access
  • • users:manage - Manage team users
  • • org:manage - Organization management

🔍 Authentication Debugging

Common Error Responses

401 Unauthorized
{
  "error": "unauthorized",
  "message": "Invalid or missing API key",
  "code": 4001
}
403 Forbidden
{
  "error": "forbidden",
  "message": "Insufficient permissions for this operation",
  "required_scope": "tunnels:write",
  "code": 4003
}
429 Rate Limited
{
  "error": "rate_limited",
  "message": "API rate limit exceeded",
  "retry_after": 60,
  "code": 4029
}

Authentication Testing

# Test API key validity
$ instatunnel auth test
✅ API key is valid
👤 User: john@example.com
📋 Plan: Pro
🔑 Permissions: tunnels:*, analytics:read
# Test specific permission
$ instatunnel auth test --scope tunnels:write
✅ Permission 'tunnels:write' granted

🔐 Security Warning: Never expose API keys in client-side code or public repositories. Use environment variables and secure key management practices. Rotate keys regularly and use minimal permissions for each key.

Need a quick path?

See plans, then jump into a guided start whenever you are ready.

For MCP endpoints on Pro/Business, use: instatunnel 8787 --mcp.

View PricingWebhook GuidesUse Cases HubGet Started Guide
InstaTunnel Docs | CLI, Webhook Testing, MCP & Troubleshooting