Private Deck Links

What It Is

A private deck link is a permanent, rotatable, unguessable capability ID in the format pd_ followed by 43 base64url characters. A Sleeved user generates one from their deck's Intelligence tab and pastes it into a partner tool (e.g. Clarent).

Unlike a share token — which expires after 24 hours and only grants read access to a deck's contents — a private deck link is non-expiring and identifies both the owner's account and the specific deck in a single value. It's the credential a partner tool uses to:

1. Prove match telemetry belongs to a specific Sleeved account and deck
2. Optionally fetch that deck's contents, even if the deck is not public

How Partners Receive It

A private deck link is never issued through the API. It is always pasted by the end user from the Sleeved app UI into your tool. Treat it as an opaque bearer credential — store it (e.g. in your tool's local settings) exactly as the user provides it. Do not attempt to derive, guess, construct, or otherwise generate a private deck link value.

Two Ways to Use It

These two uses have different transports and different failure behavior — do not assume they work the same way.

1. Read a deck's contents

Pass the raw pd_... value as the ?token= query parameter on Get deck, exactly like a share token:

curl "https://api.sleeved.gg/v1/decks/3f9a1b2c-8d4e-4a6f-9c3d-7e5b2a1f8d6c?token=pd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

The deck's own {deckId} path segment must match the deck the link was minted for — a link for deck A cannot be used to read deck B. A mismatch, a rotated link, or a never-issued link are all treated as unauthorized and return the same generic 404 that share tokens already return, with no distinguishing information about why.

Exception: if {deckId} is already a public deck, its content is returned regardless of the token — the public deck lookup takes precedence over token validation. The generic-404 behavior above only applies when the target deck is itself private.

2. Bind a telemetry submission to an account and deck

Pass it as deck.sleevedLinkId — a field in the JSON request body, not a query parameter — on the telemetry match submission endpoint. This binds the match record to the resolved owner's account and deck in one step — no separate identity/deck-association calls are needed.

This path's failure behavior is different from use #1 above: a well-formed but rotated, never-issued, or wrong-game pd_ value does not produce a 404 or any error at all — the whole submission still returns 202 {"status":"accepted"}, but that slot is silently unbound (no match record is written for it). A malformed value (doesn't match the pd_ format at all) is rejected differently — the entire request fails schema validation with 400, before any binding is attempted. See Submit match telemetry for the full oracle-safety behavior.

Rotation

The deck owner can rotate their private link at any time from the Sleeved app. Rotation immediately invalidates the old value.

• For deck reads (use #1): a partner tool still holding the old value gets the same generic 404 as if the link had never existed.
• For telemetry submissions (use #2): a partner tool still holding the old value gets a 202 with that slot silently unbound, not an error.

There is no partner-facing rotation notification either way. If match tracking silently stops working for a user, ask them to check whether they rotated their private link in the Sleeved app and need to re-paste the new value into your tool.

Failure Modes Are Indistinguishable By Design (within each use)

For deck reads (use #1): a wrong-deck link, a rotated link, and a never-issued link all produce the identical 404 — with the public-deck exception noted above. For telemetry submissions (use #2): a rotated, never-issued, or wrong-game link all produce the identical 202 with silent non-binding — but a malformed value is a distinct 400, not part of this set. This is deliberate oracle safety within each use case — the API never leaks information that would let a caller distinguish "this link used to work" from "this link never existed" from "this link belongs to someone else's deck or game," but a genuinely malformed value is a client-side request error, not a credential-validity question.

Do not build partner-side logic that tries to distinguish cases within a given use's indistinguishable set from its response. There is no distinguishing information to extract, and any such logic will simply be wrong.