Scopes
Scopes define what data your app can access. Request only the scopes you need. Users see exactly which permissions your app is requesting on the consent screen.
| Scope | Access | Endpoints |
|---|---|---|
profile:read | Read user's email, display name, and avatar | /api/v1/me, /api/v1/oauth/userinfo |
collections:read | Read user's card collections and their contents | /api/v1/collections, /api/v1/collections/{id} |
collections:write | Create collections and import cards (subject to plan limits) | /api/v1/collections (POST), /api/v1/collections/{id}/cards |
decks:read | Read user's decks, cards, deck statistics, fundamentals, and Deck Lab | /api/v1/decks, /api/v1/decks/{id}, /api/v1/decks/{id}/stats, /api/v1/decks/{id}/lab |
decks:write | Import decks into the user's account | /api/v1/decks (POST) |
Requesting Scopes
Include the scopes you need as a space-separated string in the authorization request:
scope=profile:read collections:read decks:read decks:writeScope Changes
If your app requests scopes that the user has not previously granted, they will see the consent screen again. Previously granted scopes are remembered and the consent screen is skipped when all requested scopes are already authorized.
Write Scopes
collections:write allows creating collections and importing cards.decks:writeallows importing decks into the user's account. All write operations are subject to the user's plan capacity limits, so a request can be refused for reasons that have nothing to do with your app: a user at their deck slot limit gets DECK_SLOT_LIMIT back, and your app should surface that to them rather than retrying.