API Authentication

Learn how to authenticate with the InTunnel API.

Overview

The InTunnel API uses token-based authentication. You need a valid session token to access protected endpoints.

Getting a Token

Step 1: Login

curl -X POST https://intunnel.cloud/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "you@example.com",
    "username": "yourname"
  }
}

Using the Token

Include the token in the Authorization header:

curl https://intunnel.cloud/api/tunnels \
  -H "Authorization: Bearer YOUR_TOKEN"

Token Lifetime

Token Type	Lifetime
Session token	24 hours
Tunnel token	Permanent (until regenerated)

Session vs Tunnel Tokens

Feature	Session Token	Tunnel Token
Purpose	API access	Tunnel connection
Obtained from	Login endpoint	Dashboard
Expires	24 hours	Never
Used for	API calls	CLI/GUI client

Error Responses

Invalid Credentials

{
  "success": false,
  "error": "Invalid email or password"
}

Status: 401 Unauthorized

Expired Token

{
  "success": false,
  "error": "Token expired"
}

Status: 401 Unauthorized

Missing Token

{
  "success": false,
  "error": "Authentication required"
}

Status: 401 Unauthorized

Two-Factor Authentication

If 2FA is enabled, the login process requires an additional step:

Step 1: Initial Login

curl -X POST https://intunnel.cloud/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Response (2FA Required)

{
  "success": false,
  "requires_2fa": true,
  "temp_token": "temp_abc123..."
}

Step 2: Verify 2FA

curl -X POST https://intunnel.cloud/api/verify-2fa \
  -H "Content-Type: application/json" \
  -d '{
    "temp_token": "temp_abc123...",
    "code": "123456"
  }'

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Logout

Invalidate your session token:

curl -X POST https://intunnel.cloud/api/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

1. Store tokens securely - Never commit tokens to version control
2. Use environment variables - Load tokens from environment
3. Handle expiration - Re-authenticate when tokens expire
4. Logout when done - Invalidate tokens after use

Rate Limiting

The API is rate-limited to prevent abuse:

Endpoint	Limit
Login	5 requests/minute
Other endpoints	60 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1704067200