Portfolio Intake Workflow

Portfolio intake turns artist conversations and media into review-ready evidence. It does not turn text messages into public portfolio updates automatically. The workflow keeps private media staging separate from governed upload completion and human review.

Flow

Message or call
  -> TattooAPI policy and identity evidence boundary
  -> WorkOS-scoped private media submission
  -> private R2 media staging
  -> TattooAPI upload integrity completion
  -> private worker review evidence
  -> human review
  -> approved portfolio storage
  -> TattooAPI runtime promotion only after governed approval

What Each System Does

System	Job	Authority
Communications buffer	Inbox context	Evidence source only
TattooAPI	Policy, auth, review, identity evidence, projection, and write boundary	Governing authority
Private media staging	Private temporary media staging	Evidence storage only
Upload integrity completion	Verify private object bytes, size, image signature, MIME metadata, and server-side SHA-256 before review	Staging state transition only
Private workers	Outbound private compute for classification and context loading	Review evidence only
Approved portfolio storage	Approved portfolio/media lake	Storage after review
TattooAPI runtime	Runtime mappings and canonical promotion state	Runtime truth after approval
Observability	Metadata-first observability	Trace only, not write authority

Identity Evidence, Not KYC

TattooAPI v0 uses identity evidence to help reviewers connect inbound media to artists or studios. It is not legal KYC.

Status	Meaning
`unmatched`	No reliable contact or profile evidence matched.
`phone_matched`	A normalized phone hash or contact record matched existing evidence.
`review_required`	Evidence is incomplete, ambiguous, or conflicting.
`verified_by_operator`	A human operator approved the evidence for this workflow.

Do not claim kyc_verified in v0. Legal identity verification would require a separate approved provider and policy.

Launch Caveat

Communications API access and TattooAPI readiness do not equal SMS/MMS launch readiness. A2P approval remains required before artist-facing SMS/MMS intake is production-ready.

Worker Boundary

Private workers authenticate portfolio creation and upload completion with a WorkOS organization API key in X-API-Key. The operator-context capability-claims route uses a separate short-lived WorkOS client-credentials Bearer token. These credentials are not interchangeable. Workers can request context and return evidence, but they cannot:

write directly to approved portfolio storage
mutate runtime records directly
publish public surfaces
send messages without approval
store raw phone numbers, media URLs, provider tokens, or API keys in traces

Use Portfolio Intake for the staging envelope and classification contract.

Permanent Integration

Permanent uses a dedicated Production WorkOS organization API key with exactly artists:read and portfolio_intake:stage for artist evidence reads, portfolio submission creation, and bodyless upload completion. TattooAPI maps the non-secret key ID to an approved service actor in Convex. The service mapping carries portfolio_intake:stage_cross_tenant for governed artist identity resolution and staging across approved tenants. That internal TattooAPI capability is not a WorkOS key permission. Permanent cannot approve its own submission, promote canonical runtime truth, call Sanity directly, or publish a public surface. Upload completion itself can only move verified media from awaiting_upload to awaiting_review; it cannot approve, resolve or reassign an artist, call Sanity, activate a public surface, or promote canonical runtime state. Unresolved attribution stays review-required and fail-closed with portfolioStagingAllowed=false. Identity resolution requests use the separate POST /api/private/portfolio-intake/v1/artist-resolution-requests review lane; upload completion adds no artist-resolution route.

​Portfolio Intake Workflow

​Flow

​What Each System Does

​Identity Evidence, Not KYC

​Launch Caveat

​Worker Boundary

​Permanent Integration