Documentation Index
Fetch the complete documentation index at: https://docs.flexslot.gg/llms.txt
Use this file to discover all available pages before exploring further.
Scopes are how your app tells Flexslot — and the user — exactly what it wants to do. Each scope is a short, colon-separated string. You request them as a space-separated list on the /authorize request:
scope=decks:read sideboards:write guides:read
Catalog
Scopes are additive and minimum-necessary. Request only what you need for the operation in front of the user. You can request more scopes later via incremental authorization (start a new flow with the additional scopes).
Decks
| Scope | Grants |
|---|
decks:read | List the user’s decks, read deck details, read cards, read deck metadata |
decks:write | Create, update, and delete the user’s decks. Modify cards. (Implies decks:read.) |
Sideboards
| Scope | Grants |
|---|
sideboards:read | List the user’s sideboards, read sideboard contents and matchup plans |
sideboards:write | Create, update, and delete sideboards. Modify matchup plans. (Implies sideboards:read.) |
Sideboard Guides
| Scope | Grants |
|---|
guides:read | Read the user’s sideboard guides, including matchup write-ups and strategy notes |
guides:write | Create, update, and delete sideboard guides. Modify matchup notes. (Implies guides:read.) |
Cards
| Scope | Grants |
|---|
cards:read | Look up cards in the Flexslot card database (autocomplete, batch fetch, card details) |
cards:read does not access any user-specific data. It’s the same read-only card data available on the public site. Most integrations need this alongside decks:read because deck contents reference cards.
Exports
| Scope | Grants |
|---|
exports:read | Generate Excel, DOCX, and PDF exports of the user’s decks and sideboard guides |
How scope strings combine
Request multiple scopes by separating them with spaces (which are %20 once URL-encoded):
scope=decks:read sideboards:read guides:read cards:read
decks:write includes decks:read — you don’t have to request both. But explicitly requesting both is harmless and makes the consent screen unambiguous.
What the user sees
For scope=decks:read sideboards:write, the consent screen shows:
Quickstart Test wants to:
- Read your decks
- Manage your sideboards (create, edit, delete)
Phrasing comes from a Flexslot-controlled catalog. You can’t customize the text.
Down-scoping
Flexslot may grant fewer scopes than you requested. The /token response always tells you which scopes were actually granted:
{
"access_token": "fst_at_…",
"scope": "decks:read sideboards:read",
"...": "..."
}
scope field in the response will reflect what they approved. Check it. Don’t assume you got everything you asked for.
Scope enforcement on the API
The resource server checks scopes per-endpoint. A token with only decks:read calling POST /decks/ gets:
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="flexslot",
error="insufficient_scope",
error_description="Requires scope: decks:write",
scope="decks:write"
insufficient_scope, the fix is not to retry — it’s to start a new authorization flow that requests the missing scope.
Incremental authorization
Instead of requesting every possible scope on first login, start with the minimum and request more when you need them.
First login: minimum scopes
scope=decks:read — just enough to show the user their decks.
User clicks Export
Now you need exports:read. Start a new flow with scope=decks:read exports:read.
User keeps using the app
The new token has both scopes. You don’t lose the user’s prior consent — Flexslot remembers it.
- Trust: users are warier of apps that demand everything up front
- Recovery: if a scope check fails on the API, you have a clear path forward
Don’t request scopes you might use someday. The minimum-necessary rule is enforced socially (users notice, write-ups happen) and reputationally. Pages with sprawling consent screens convert worse.
Scope vs role
Scope is what the app can do. The user’s role on Flexslot still controls whether they’re allowed to do it at all. A free-tier user’s token with decks:write can’t, for example, exceed the free-tier deck limit. The 403 comes from the resource server with a different error than insufficient_scope.
Future scopes
We add scopes when we add public API surface. If you need access to a Flexslot capability that doesn’t have a scope yet, open a feedback ticket — these docs and the scope catalog are kept in sync.
