Skip to main content

​
Authentication

TattooAPI uses approved partner and owner credentials for authenticated beta routes. The credential proves who the caller is. TattooAPI then maps that identity to an actor, role, organization, studio scope, and artist scope before returning protected data.
Public no-auth reads stay available for GET /health and GET /studios. Everything else in the beta requires approved credentials plus a mapped TattooAPI actor.

​
Access Paths

​
Response Semantics

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

​
Get Access

Access is granted by identity plus mapping:
  1. Sign in at https://partners.tattoo.dev.
  2. Join or select the approved organization for your studio, agency, or builder team.
  3. Create a partner API key from the portal.
  4. TattooAPI maps the non-secret key identity to your actor role and permissions.
  5. Open https://docs.tattoo.dev and test in the Mintlify playground with X-API-Key.
  6. TattooAPI validates the credential, then resolves the actor mapping before returning protected data.
TattooAPI stores only non-secret credential identity metadata in actor mappings. API key secret values stay in the partner portal, secret stores, or the encrypted docs handoff, never in public docs. Never put API key secret values in Mintlify docs, git, source-pack reports, prompts, screenshots, or public examples.
Docs playground prefill uses an encrypted partner key handoff. The full key is shown once, encrypted for a 24-hour browser/docs session, and never stored in plaintext in public docs.

​
Docs Playground Prefill

When docs personalization is enabled for docs.tattoo.dev, the playground fills X-API-Key only when all of these checks pass:
  • the browser has an active WorkOS session on partners.tattoo.dev
  • the encrypted docs key belongs to the same WorkOS user and organization
  • TattooAPI confirms the user still has partner_api_keys:manage
  • the encrypted docs key handoff has not expired
If docs personalization is not enabled in the current Mintlify deployment, copy the one-time key from partners.tattoo.dev and paste it into the playground X-API-Key header manually. Do not paste it into chat, screenshots, docs pages, source files, or commits. OpenAPI operation security is the playground source of truth: machine-key examples use ApiKeyAuth with X-API-Key, while human session examples use BearerAuth.

​
Machine-to-Machine Model

TattooAPI currently uses WorkOS organization API keys for API-key-based M2M authentication. It does not use OAuth client credentials for this path.
  1. A private service sends its WorkOS organization API key in X-API-Key.
  2. WorkOS validates the secret and returns the non-secret key identity, organization owner, and permission metadata.
  3. TattooAPI loads the key ID’s active Convex actor mapping.
  4. TattooAPI enforces the mapped role, permissions, organization, studio scope, artist scope, and any explicitly approved internal service capability.
  5. Unmapped keys return 403, even when WorkOS validated the credential.
WorkOS owns credential lifecycle. TattooAPI remains the authorization, review, and write boundary.

​
V1 API Key Permissions

V1 partner keys are read/private-worker scoped, with one governed write capability: private portfolio intake staging. Staging creates a review-required record and private upload target; it does not write to Sanity, mutate canonical runtime data, or publish a public surface. Platform-supported mapped permissions:
  • studios:read
  • artists:read
  • search:read
  • portfolios:read
  • designs:read
  • owner_portfolio_assets:read
  • agent_context:read
  • portfolio_intake:review
  • portfolio_intake:classify
  • portfolio_intake:stage
The following are intentionally not available in v1 partner keys: artists:write, bookings:manage, and portfolios:publish. portfolio_intake:stage is available through the partner portal as an explicit advanced permission. portfolio_intake:review is reserved for separately mapped operator identities and is not granted by the self-service key form. Approved service actors can also receive the internal portfolio_intake:stage_cross_tenant mapping capability. That capability is not selectable on a WorkOS key, is never granted to self-service partner keys, and permits only governed identity resolution and staging. It does not grant review, approval, Sanity promotion, canonical runtime promotion, or publication.

​
Credential + Actor Boundary

The credential layer owns:
  • user authentication
  • organization membership
  • browser sessions
  • API key lifecycle
  • MCP OAuth authorization metadata
TattooAPI 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. Create, rotate, and revoke machine credentials in the partner portal. TattooAPI stores only non-secret identity metadata and actor mappings. It does not store API key secret values in docs, source packs, reports, or git. See API Keys for the current route behavior.

​
Private Workers

Private worker tooling is internal-only in this phase.
  • Server-to-server tools should use partner API keys.
  • OAuth clients should use approved 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.