> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tattoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Current public and authenticated-beta access posture for TattooAPI.

# 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.

<Note>
  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.
</Note>

## Access Paths

| Caller                    | Credential            | Header                          | Current posture                           |
| ------------------------- | --------------------- | ------------------------------- | ----------------------------------------- |
| Public reader             | None                  | None                            | Health and studios only                   |
| Team member               | Approved bearer token | `Authorization: Bearer <token>` | Internal beta after actor mapping         |
| Machine or private worker | Partner API key       | `X-API-Key: <key>`              | Internal beta after actor mapping         |
| Studio or artist owner    | Approved bearer token | `Authorization: Bearer <token>` | Owner-scoped creative reads after mapping |

## 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.

<Note>
  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.
</Note>

## 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](/api-reference/authentication/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](/guides/agent-and-hydration-boundaries).