Skip to main content

​
Authentication

TattooAPI now uses WorkOS as the default authentication authority for authenticated and internal-beta routes. Convex remains the TattooAPI runtime and authorization-mapping authority. WorkOS proves who the caller is; Convex maps that identity to a TattooAPI actor, role, organization, and owner scope.
Public no-auth reads stay available for GET /health and GET /studios. Everything else in the internal beta requires WorkOS auth plus a mapped TattooAPI actor.

​
Access Paths

CallerCredentialHeaderCurrent posture
Public readerNoneNoneHealth and studios only
Team memberWorkOS/AuthKit bearer tokenAuthorization: Bearer <token>Internal beta after actor mapping
Machine or agentWorkOS API KeyX-API-Key: <key>Internal beta after actor mapping
Studio or artist ownerWorkOS/AuthKit bearer tokenAuthorization: Bearer <token>Owner-scoped creative reads after mapping

​
Response Semantics

  • Missing credentials return 401.
  • Invalid WorkOS credentials return 401.
  • Valid WorkOS credentials without an active TattooAPI actor mapping return 403.
  • Retired local API-key management routes return 410.

​
WorkOS + Convex Boundary

WorkOS owns:
  • user authentication
  • organization membership
  • AuthKit sessions
  • API key lifecycle
  • MCP OAuth authorization metadata
Convex owns:
  • TattooAPI actor mapping
  • ontology-scoped authorization
  • owner studio and artist scopes
  • runtime truth and operator lineage

​
Internal Beta

Internal beta routes are not public product surface yet. Current authenticated internal reads include:
  • GET /api/v1/search
  • GET /api/v1/artists
  • GET /api/v1/artists/[id]
  • GET /api/v1/portfolios
  • GET /api/v1/portfolios/[id]
  • GET /api/v1/designs
  • GET /api/v1/designs/[id]
Owner-scoped creative reads include:
  • GET /api/v1/me/portfolio-assets
  • GET /api/v1/me/portfolio-assets/[id]
  • GET /api/v1/me/designs
  • GET /api/v1/me/designs/[id]

​
API Keys

Local TattooAPI API key creation is retired in WorkOS mode. Create, rotate, and revoke machine credentials in WorkOS API Keys. TattooAPI stores only non-secret WorkOS identity IDs and actor mappings. It does not store API key secret values in Convex, docs, source packs, Mastra reports, or git. See API Keys for the current route behavior.

​
MCP And Agents

Mastra and MCP are internal-only in this phase.
  • Mastra local tools should prefer a WorkOS API key for server-to-server calls.
  • MCP clients should use WorkOS/AuthKit OAuth bearer tokens.
  • Runtime mutations remain approval-gated and dry-run by default.
  • Prompt-provided actor claims are never authority by themselves.
For the current public-safe agent posture, see Agent And Hydration Boundaries.