Share Tokens

Share tokens let Sleeved users grant temporary access to their private decks without making them publicly visible. As an integration partner, you receive tokens from users and use them to access decks on their behalf.

How Tokens Work

• Tokens are valid for 24 hours from the time they are created
• 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
• All token failure paths return 404. The API does not reveal whether a token existed, was valid for a different deck, or has expired

The Untap.in Integration Flow

Tokens are created by Sleeved users through the app UI. As a partner, you do not create tokens — you receive them.

The flow is:

1. A Sleeved user opens a deck in the deck builder and clicks "Share to Untap"
2. A share URL is copied to their clipboard in the format:

   https://sleeved.gg/{gameSlug}/decks/{deckId}?token={token}

3. The user pastes the URL into the Untap.in import field (or shares it with you through your integration's UI)
4. You extract the deckId and token from the URL
5. Use them with the deck endpoints to fetch the deck data

Using a Token

Pass the token as a token query parameter on any deck endpoint:

# Fetch deck JSON
curl "https://api.sleeved.gg/api/v1/decks/deck_abc123?token=tok_xyz789" \
  -H "X-API-Key: slvd_live_your_key_here"

# Export as Untap text format
curl "https://api.sleeved.gg/api/v1/decks/deck_abc123/text?format=untap&token=tok_xyz789" \
  -H "X-API-Key: slvd_live_your_key_here"

Extracting Token and Deck ID from a Share URL

Given a share URL like:

https://sleeved.gg/digimon/decks/deck_abc123?token=tok_xyz789

Extract the components as follows:

• Deck ID: the path segment after /decks/ → deck_abc123
• Token: the token query parameter → tok_xyz789

Both are required when calling the deck endpoints for a private deck.

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 same error message is returned for all cases.

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 Generation (Internal Reference)

Tokens are created by Sleeved's authenticated API at POST /decks/:deckId/share-token. This endpoint requires a Sleeved user session and is not available to API partners — it is documented here for completeness only.

Sleeved users are limited to 20 share tokens per hour per account to prevent abuse.