Authentication and Auth Failures

In Short

Flicker Fox sandbox routes require X-Sandbox-Auth; production launch and partner-switch use employer Tapestry session context; callbacks use partner signing keys. All failures return SPEC-001 error envelopes — branch on stable code values, never on localized message text.

Enterprise Identity Providers

Employer SSO through Okta or similar IdPs is configured at the Tapestry federation boundary — separate from partner API credentials. See Okta Integration and Identity Federation for the architecture overview.

Environment Separation

Production — https://tapestry.querytek.io for launch, partner-switch, and signed callbacks
Sandbox (Flicker Fox) — same host; protected routes under /v1/sandbox/flicker-fox/*
Local stack — http://localhost:32000 for developer compose only

See Partner SDK for install paths and the environment reference table.

Sandbox Credentials

Self-serve developers register at Developer Account, verify email, then bootstrap Flicker Fox credentials. The one-time auth_value is shown once — store it securely and send it as X-Sandbox-Auth on sandbox API calls.

Missing or invalid sandbox auth → fail closed (401 / auth error envelope)
Valid credential → requests scoped to issued sandbox partner context

Production Partner APIs

POST /v1/launch, POST /v1/partner-switch — session and tenant context from employer Tapestry session; call from authenticated partner UI context
POST /v1/callbacks/partner/{partner_key} — partner signs payload; Tapestry validates HMAC signature

Production signing keys are operator-governed. Do not embed long-lived secrets in client-side code or public repositories.

When Auth or Validation Fails

Tapestry returns JSON error envelopes with stable code fields. Required partner behavior:

Branch on code, not on message or message_localized.
Never log sandbox credentials, signing keys, or raw tokens.
Include correlation_id from responses in support tickets.

Code	Typical meaning
`AUTH_INVALID`	Session or auth context invalid
`TENANT_SCOPE_INVALID`	Cross-tenant or scope mismatch
`PARTNER_NOT_ENABLED`	Partner not launch-eligible for tenant
`CONTEXT_INVALID`	Malformed `context_values`
`PARTNER_ADAPTER_NOT_FOUND`	Unknown or unregistered partner key
`CIRCUIT_BREAKER_OPEN`	Temporary route cooldown — respect `details.cooldown_seconds` when present
`PARTNER_CALLBACK_INVALID`	Callback signature or payload rejected (`400`) — fix signing material; do not retry blindly

SDK helpers: TapestryApiError / parseErrorEnvelope() on the Partner SDK.