API Reference

Overview

stunl exposes two APIs. The gRPC API is what the stunl CLI and SDKs use for low-latency streaming — tunnel lifecycle, request/response framing, real-time events. The REST API at api.stunl.com is for everything else: account management, tunnel CRUD, webhooks, Inspector captures, and integrations from any HTTPS-capable client.

REST API

The REST API at https://api.stunl.com is OpenAPI-compatible and works from any HTTPS client. Responses are JSON; sensitive data uses Cache-Control: no-store. All endpoints (except /health and /api/version) require an Authorization: Bearer <token> header.

$ curl https://api.stunl.com/health
{"status":"healthy"}

$ curl https://api.stunl.com/api/version
{"service":"portal","version":"5.35.0","git_sha":"abc1234"}

$ curl -X POST https://api.stunl.com/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email":"you@example.com","password":"hunter2"}'
{"access_token":"eyJ…","refresh_token":"eyJ…","expires_in":3600}

$ curl https://api.stunl.com/api/account \
    -H "Authorization: Bearer $TOKEN"

gRPC Authentication

For the gRPC API, include your API key in the metadata.

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/metadata"
)

// Create gRPC connection with API key
func connectWithAuth(apiKey string) (*grpc.ClientConn, error) {
    // Add API key to context
    ctx := metadata.AppendToOutgoingContext(
        context.Background(),
        "x-api-key", apiKey,
    )
    
    conn, err := grpc.DialContext(ctx,
        "portal.stunl.com:9090",
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
    )
    return conn, err
}

gRPC Services

TunnelService

The main service for creating and managing tunnels.

message CreateTunnelRequest {
  string      tunnel_id = 1;       // Custom tunnel ID (optional)
  TunnelType  tunnel_type = 2;     // HTTP, TCP, UDP
  int32       local_port = 3;      // Local port to tunnel
  string      local_host = 4;      // Local host (default: localhost)
  string      domain = 5;          // Custom domain (optional)
  bool        use_root_domain = 6; // Use root domain
  string      password = 7;        // Basic auth password
  int32       preferred_port = 8;  // Reserved public port
  TunnelOAuthConfig oauth = 9;   // OAuth configuration
}

message CreateTunnelResponse {
  string     tunnel_id = 1;     // Assigned tunnel ID
  string     public_url = 2;    // Public HTTPS URL
  string     public_addr = 3;   // Public hostname
  int32      public_port = 4;   // Public port (for TCP/UDP)
  TunnelType tunnel_type = 5;  // Tunnel type
  int32      local_port = 6;    // Local port
}

enum TunnelType {
  TUNNEL_TYPE_UNSPECIFIED = 0;
  TUNNEL_TYPE_HTTP = 1;
  TUNNEL_TYPE_TCP = 2;
  TUNNEL_TYPE_UDP = 3;
  TUNNEL_TYPE_WEBSOCKET = 4;
}

message DestroyTunnelRequest {
  string tunnel_id = 1;
}

message DestroyTunnelResponse {
  bool success = 1;
  string message = 2;
}

message ListTunnelsRequest {}

message ListTunnelsResponse {
  repeated TunnelInfo tunnels = 1;
}

message TunnelInfo {
  string     tunnel_id = 1;
  string     public_url = 2;
  TunnelType tunnel_type = 3;
  int32      local_port = 4;
  int64      created_at = 5;
  int64      bytes_in = 6;
  int64      bytes_out = 7;
}

OAuth Configuration

Configure OAuth authentication for your tunnels.

message TunnelOAuthConfig {
  AuthProvider provider = 1;            // OAuth provider
  repeated string allowed_domains = 2;  // Email domain whitelist
  repeated string allowed_emails = 3;   // Specific email whitelist
  repeated string github_orgs = 4;      // GitHub org restrictions
  repeated string github_teams = 5;     // GitHub team restrictions
}

enum AuthProvider {
  AUTH_PROVIDER_UNSPECIFIED = 0;
  AUTH_PROVIDER_GITHUB = 1;
  AUTH_PROVIDER_GOOGLE = 2;
  AUTH_PROVIDER_MICROSOFT = 3;
}

Data Streaming

Once a tunnel is created, data flows through bidirectional gRPC streams.

service HTTPTunnelService {
  // Bidirectional stream for HTTP requests/responses
  rpc StreamHTTP(stream HTTPRequest) returns (stream HTTPResponse);
}

message HTTPRequest {
  string request_id = 1;
  string method = 2;
  string path = 3;
  map<string, string> headers = 4;
  bytes body = 5;
}

message HTTPResponse {
  string request_id = 1;
  int32 status_code = 2;
  map<string, string> headers = 3;
  bytes body = 4;
}

service TCPTunnelService {
  // Bidirectional stream for raw TCP data
  rpc StreamTCP(stream TCPData) returns (stream TCPData);
}

message TCPData {
  string connection_id = 1;
  bytes data = 2;
  bool eof = 3;
}

Error Handling

The API uses standard gRPC status codes with additional error details.

Rate Limits

Client Libraries

Official and community client libraries are available:

Related Documentation

• CLI Reference →
• Kubernetes Integration →
• Multi-port Tunneling →