scope is a comma-separated list of which parts of the API your app can access on behalf of an authenticated user.
This is what a user is shown by pnut.io for each scope they are authorizing:
- basic - see basic information about you
- stream - read your post streams
- write_post - create and interact with your posts
- follow - add and remove follows, mutes, and blocks for you
- update_profile - update your name and other profile information
- presence - update your presence
- messages - send and receive public and private messages
- public_messages - send and receive public messages
- files - manage your files
- polls - manage your polls
- email - access your email address
It's encouraged that you use extended scopes whenever reasonable, as it will reduce how much your app needs to filter out, and reduce the surface area for users' data to go places they don't want it to.
Channels, Files, and Polls currently allow extended scopes. Extended scopes allow you to only authorize use of the channel types that your app needs access to. For example, if you only will be dealing with private messages, you should request the
messages:io.pnut.core.pm scope. If your app has its own public-only channel type, you could request the
public_messages:com.example.site scope. Or if it only needs to view and delete files for itself, you could request
If the scopes you initially requested have changed, your users may have authorized some, but not all, of those scopes. If so, you can send them back through the authorization flow and it will ask for the new scopes to be allowed.
Your client can tell what scopes a user has authorized for your client by the
X-OAuth-Scopes return header on a request, or by directly requesting their Token.
In the documentation, anscope indicates that an app token is required for the endpoint.
basic scope only allows access to any endpoints in the API that require access token. If any other scope is authorized,
basic is redundant.
This scope is not needed for uploading files. It allows clients to update, attach, and delete files without including a
Special Extended File Scopes
There are two special file scopes:
files:core_audio gives access to all files with
kind: audio, and
files:core_image gives access to all files with
kind: image. These do not currently trigger App Stream objects; specific file types or the whole
files scope would need to be specified to use App Streams with files.
This scope works similarly to files, and is not needed to create and attach polls to posts and messages, but lets users attach and delete polls without a
App Streams do not notify of email address changes.