Share Tokens

How Tokens Work

• Tokens are valid for 24 hours from the time they are created. Expired tokens are automatically purged from server-side storage shortly after expiry (Firestore native TTL)
• A token is multi-use within its validity window — you can fetch the same deck multiple times with the same token
• Tokens are scoped to a single deck — a token for deck A cannot be used to access deck B
• Tokens are bearer credentials: any caller who presents a valid (deckId, token) pair receives the deck. Treat tokens like passwords
• Token failure paths return 404 — the API does not distinguish between "token does not exist", "token expired", or "token belongs to a different deck" in the response body

The Integration Flow

Tokens are created by Sleeved users through the app UI. The flow is:

1. A Sleeved user opens a deck in the deck builder and clicks a share option (e.g. "Share to Untap", "Copy TTS Link")
2. A share URL is copied to their clipboard in the format:

   https://sleeved.gg/api/decks/{deckId}?format=ga-tts&token={token}

3. The user pastes the URL into the target tool (Untap.in, Tabletop Simulator, etc.)
4. The tool fetches the deck directly — no API key required

The sleeved.gg/api/decks/ path proxies to the API automatically.

Using a Token

Pass the token as the ?token= query parameter on the deck endpoint. Both the friendly URL and the direct API URL work:

# Via sleeved.gg (friendly URL — recommended for users)
curl "https://sleeved.gg/api/decks/deck_abc123?token=tok_xyz789"

# Via API directly (equivalent)
curl "https://api.sleeved.gg/v1/decks/deck_abc123?token=tok_xyz789"

# With format parameter
curl "https://sleeved.gg/api/decks/deck_abc123?format=ga-tts&token=tok_xyz789"

The deck endpoint is unauthenticated — no X-API-Key header is needed.

Token Errors

All token-related errors return 404 Not Found. The response body is:

{
  "error": "Deck not found or not public"
}

This covers: token does not exist, token has expired, token belongs to a different deck, and deck does not exist. The error message is identical for all four cases to prevent information leakage.

If a user reports that their shared link is not working, ask them to generate a new share link from the Sleeved app — the token may have expired.

Token Revocation

The deck owner can rescind any share token they have issued without waiting for the 24-hour expiry. Revocation is performed from the Sleeved app. Three controls are exposed to the owner:

• List active tokens for a deck — surfaces token prefix + creation/expiry timestamps so the owner can audit who currently has access. The full token is never re-displayed.
• Revoke a specific token by prefix — pinpoint revocation of a single suspect link.
• Mass-revoke all tokens for a deck ("panic button") — revokes every active token for that deck in one call.

Revocations are effective immediately — there is no positive cache for share tokens. If a tool receives a 404 after a previously-working token, the recovery path is the same: the user generates a new share link.