Launch and Callback

In Short

Partners validate inbound Tapestry launch handoffs on their own origin, initiate governed routing with POST /v1/launch and POST /v1/partner-switch, and post HMAC-signed callbacks to Tapestry. Use correlation IDs, idempotency keys on switches, and fail-closed error handling throughout.

Inbound Launch (Partner Receives Handoff)

When Tapestry routes a user to your product:

1. Validate the incoming assertion or token on your origin before creating a local session.
2. Map Tapestry canonical claims to your user record.
3. Enforce authorization in your application — Tapestry does not run your business logic after handoff.

Inbound token validation is partner-product specific (OIDC, signed assertions, etc.). See partner playbooks on querytek.io/docs for production patterns.

Outbound Launch and Partner Switch

From an authenticated employer context, partner UI may call:

• POST /v1/launch — start a governed launch (postLaunchPartnerSubset)
• POST /v1/partner-switch — switch partner context (postPartnerSwitchPartnerSubset)

Include optional X-Correlation-Id and Idempotency-Key on partner-switch operations. Success returns RoutingDecisionResponse with decision_result and redirect_url when routing succeeds.

context_values must use string, integer, or boolean values only. Undocumented keys may return CONTEXT_INVALID.

API reference: Partner API (ReDoc) · Partner SDK

Outbound Callbacks (Partner → Tapestry)

POST /v1/callbacks/partner/{partner_key} (postPartnerCallback)

1. Build JSON with tenant_id and nested callback payload (include event).
2. Compute HMAC-SHA256 over canonical JSON {tenant_id, partner_key, payload} (sorted keys, compact separators).
3. Send the signature via X-Callback-Signature (preferred), ?signature= query, or body signature — Tapestry resolves in that order.
4. Handle 400 (invalid signature/payload) and 503 (unavailable) without retry storms; design idempotent events.

Use placeholder signing material in examples only (REPLACE_ME). Never publish production signing keys.

See also: Callback and Event Catalog · Authentication and Auth Failures

Flicker Fox Is Not Production Launch

Sandbox self-test uses /v1/sandbox/flicker-fox/* only. Do not substitute Flicker Fox for Textmetrics, Trusaic, or other registry partners in production.