Skip to content
Launch Rail
Documentation

Identity Service

A Go service for company, user, team, and membership management with pluggable authorization, OpenTelemetry, documented application APIs, and governed agent access through the Agent Gateway pilot.

Quickstart

Get Identity up and running in minutes using our Docker-based local development environment.

# 1. Clone & Start
git clone https://github.com/launchrail/identity
cd identity
docker-compose up -d

# 2. Run initial migrations
make migrate-up

CLI Interaction

launchrail-ctl — zsh
$
CLI SimulationActive

Local Run & Dev

The Identity service is a highly optimized Go microservice designed for high-concurrency user and membership operations.

Bootstrap Environment

git clone https://github.com/launch-rail/identity.git
cd identity
make dev-setup
docker-compose up -d

The make dev-setup command initializes dependencies and regenerates protobuf + SQLC artifacts.

Client SDK Usage

const { user, error } = await identity.signIn({
  email: "user@example.com",
  password: "secure-password"
});

if (user) {
  // Session is automatically established via secure cookies
  window.location.href = "/dashboard";
}

Architecture

Stateless authentication with session-shadowing. Identities are verified at the edge, while authorization is enforced at the core.

Entry Points
gRPC
MCP Agent
Service Logic
Domain Engine
Persistence
PostgreSQL
NATS Bus

Core Domain Entities

Our data model is built for B2B SaaS complexity, supporting multi-tenant isolation and granular membership roles.

User

The primary identity entity. Linked to authentication providers (Kratos, Zitadel) and audit trails.

Company (Tenant)

The root tenant container. Controls domain white-labeling, billing context, and global settings.

Team

A logical grouping of users within a company. Supports nested hierarchies and team-specific permissions.

Membership

The join entity mapping Users to Companies/Teams with specific Roles and Permissions.

Configuration Reference

Configure the service via Environment Variables or a config.yaml file.

Core Service Settings

VariableDefaultDescription
PORT8080HTTP/ConnectRPC listener
ENVIRONMENTdevelopmentSet to production for strict validation
TRUSTED_PROXY_CIDRS-Required in prod for identity header trust

Infrastructure State

Relational: PostgreSQL

Main source of truth for all domain entities. Use a connection pool for production.

const response = await identity.verifyMfa({
  userId: "user-123",
  code: "123456",
  strategy: "TOTP"
});

Ephemeral: Redis

Used for distributed caching of authorization results and session lookups.

REDIS_ENABLED=true
REDIS_ADDR=localhost:6379

Event Bus Providers

The service emits events for all mutations (e.g., user.created, company.updated).

const response = await identity.validateSession({
  token: "session-token-from-cookie"
});

if (response.valid) {
  console.log("Authenticated as:", response.user.email);
}

Authorization Architecture

Pluggable check engine supporting local database evaluation or remote providers like Ory Keto or Zitadel.

Check Providers

  • Database: Eval permissions via SQL joins (Good for simple SaaS)
  • Ory Keto: Google Zanzibar-style tuple checking
  • Zitadel: Built-in IAM and policy evaluation

Resilience

Remote providers are automatically wrapped with:

  • • Automatic Retries
  • • Circuit Breakers
  • • LRU In-Memory Caching

Policy & Overrides

Control mapping from high-level roles to granular permissions via JSON policy overrides.

{
  "AUTH_POLICY_OVERRIDES": {
    "organization_admin": ["read", "write", "manage_billing", "delete_company"],
    "team_lead": ["read", "write", "manage_members"]
  }
}

Deployment & Operations

Recommended Production Controls

  • • Set ENVIRONMENT=production to enable strict header validation.
  • • Use cmd/migrator as a k8s init-container or pre-deploy job.
  • • Configure OTEL_COLLECTOR_URL for trace export.

GCP / Cloud Run reference · planned

This command shape is an implementation reference, not a supported deployment promise. The customer-run AWS path is validated first; GCP artifacts will be offered only after an equivalent release gate.
# Build image
gcloud builds submit --tag gcr.io/$PROJECT_ID/identity .

# Deploy manually
gcloud run deploy identity \
  --image gcr.io/$PROJECT_ID/identity:latest \
  --region us-central1 \
  --platform managed \
  --set-env-vars ENVIRONMENT=production,DATABASE_URL=...
Frequently Asked Questions

Common Questions & Answers

Everything you need to know about integrating and hosting this Launch Rail service.

Related services

AuthzAudit LogSubmissions

Related use cases

HealthcareFintechPropTech