Scopes
A scope is one thing a member can allow your application to do. You ask for scopes in the scope parameter of the authorisation link; the member sees each in plain words on the consent screen; the token you get carries exactly those.
Names are a contract: once a scope exists its name never changes, and scopes are only ever added.
| Scope | Lets your application | Status |
|---|---|---|
identify | See the member's id, username, display name and picture | Available |
email | See the member's verified e-mail address. Shown with a warning colour on the consent screen. | Available |
servers | See which servers the member is in (id, name, icon, colour, whether they own it) | Available |
bot | Add your application's bot to a server the member manages, with the permissions they choose | Available |
servers.join | Add the member to a server your bot is in | Planned |
library.read | See the member's game shelves, stars and Moymo Index ratings | Planned |
playtime.read | See how long the member plays each game, this week, and what they are playing now | Planned |
profile.read | See what is on the member's profile page: about text, links, badges, level | Planned |
friends.read | See who the member follows and who follows them | Planned |
activity.write | Post to the member's activity ("started playing") | Planned |
applications.commands | Add your application's commands to a server | Planned |
webhook.incoming | Create an incoming webhook in a channel the member picks | Planned |
role_connections.write | Set the member's game connections for server roles | Planned |
A planned scope has a name so that this page, the portal and the SDKs can mention it, but you cannot ask for it yet: the consent screen would promise something no endpoint does. Asking for one answers invalid_scope.
There is also one scope you cannot ask for: developer, which lets Moymo's own Developer Portal manage a member's applications. Only Moymo's own client can be given it.
What a token is, and is not
An access token acts as the member for the scopes it carries and for nothing else. It works on the App API and nowhere else; it cannot reach the member's settings, library or messages unless a later scope says so, and it can never touch the account's security (password, sessions, deletion).
For example, with identify alone:
| Request | Answer |
|---|---|
GET /api/app/v1/users/@me | The member: id, username, display_name, avatar. No email. |
GET /api/app/v1/users/@me/servers | 403: the token does not have the servers scope. |
Asking for little
Ask for the least you need. The member sees the list, and a longer list is a reason to say no. If you need more later, send the member through the flow again with the larger list. The screen shows the whole list, and says so when they have already allowed all of it.