taco-api

The central REST API for the TACO platform. Serves the frontend and handles all user-facing operations.

Overview

Property	Value
Language	Go
Framework	Echo v4
Port	8090
Exposed	Internal only (via HAProxy through taco-nextjs)
Dependencies	MySQL, Valkey
Repository	tacosec/taco-api

Architecture

taco-api is a monolithic REST API that provides:

• User authentication (email/password + OAuth via GitHub and Google)
• JWT session management with Valkey-backed refresh tokens
• Multi-tenant subscription and project management
• RBAC with owner/admin/member roles at both subscription and project level
• Vulnerability finding queries with filtering, trends, and summaries
• SBOM listing, detail views, diffing, and aggregation
• Component management with dependency trees
• Secret management
• Alert configuration
• Risk scoring configuration
• Stripe billing integration
• Audit logging

Data Stores

• MySQL -- Primary datastore. Owns the users, subscriptions, subscription_members, projects, project_members, api_tokens, project_finding_statuses, finding_audit_log, audit_log, scan_requests, image_scan_requests, project_risk_config, alert_channels tables. Reads from findings, sboms, components, sbom_components, secrets tables owned by other services.
• Valkey (Redis DB 1) -- Stores JWT refresh sessions. TTL-based expiration.

Key Packages

Package	Purpose
auth/	JWT manager, password hashing (bcrypt), session store (Redis), OAuth clients (GitHub, Google)
config/	Environment variable loading
handler/	HTTP handlers: auth, oauth, user, subscription, project, token, alert, secret, dashboard, billing, enrich
middleware/	CORS, JWT auth, RBAC (subscription-level and project-level role checks)
model/	MySQL data access: UserStore, SubscriptionStore, ProjectStore, TokenStore, FindingStore, SecretStore, BillingStore
enrichment/	Client-side enrichment logic for API responses

Authentication Flow

1. Register/Login -- POST /api/v1/auth/register or POST /api/v1/auth/login returns an access token (short-lived JWT) and a refresh token (stored in Valkey).
2. OAuth -- GET /api/v1/auth/github or GET /api/v1/auth/google initiates OAuth flow. Callback endpoints create/link user accounts and return tokens.
3. Refresh -- POST /api/v1/auth/refresh exchanges a valid refresh token for a new access token.
4. Protected routes -- All /api/v1/* routes (except auth and billing webhook) require a valid JWT in the Authorization: Bearer <token> header.

RBAC Model

• Subscription roles: owner, admin, member
• Project roles: owner, admin, member
• Write operations (create, update, delete) require owner or admin
• Read operations require any role (owner, admin, or member)
• Role checks are implemented as Echo middleware (RequireSubscriptionRole, RequireProjectRole)

Environment Variables

Variable	Required	Default	Description
PORT	No	8090	HTTP listen port
MYSQL_DSN	Yes	--	MySQL connection string
REDIS_URL	Yes	--	Valkey/Redis URL (DB 1)
JWT_SECRET	Yes	--	Secret for signing JWTs
GITHUB_CLIENT_ID	No	--	GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	No	--	GitHub OAuth app client secret
GOOGLE_CLIENT_ID	No	--	Google OAuth client ID
GOOGLE_CLIENT_SECRET	No	--	Google OAuth client secret
OAUTH_CALLBACK_BASE	No	--	Base URL for OAuth callbacks
FRONTEND_URL	No	--	Frontend URL for CORS and redirects
STRIPE_SECRET_KEY	No	--	Stripe API secret key
STRIPE_WEBHOOK_SECRET	No	--	Stripe webhook signing secret
STRIPE_PRICE_PRO_MONTHLY	No	--	Stripe price ID for Pro plan
STRIPE_PRICE_ENTERPRISE_MONTHLY	No	--	Stripe price ID for Enterprise plan

Health Check

GET /healthz -- Returns 200 OK when both MySQL and Valkey are reachable. Returns 503 with detail if either is down.