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 for each scope they are authorizing:
- basic - see basic information about you
- email - access your email address
- files - manage your files
- follow - add and remove follows, mutes, and blocks for you
- messages - send and receive public and private messages
- public_messages - send and receive public messages
- polls - manage your polls
- presence - update your presence
- stream - read your post streams
- update_profile - update your name and other profile information
- write_post - create and interact with your posts
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
When authorizing scopes, users will have the choice of not authorizing all new scopes. This is an example of what they might see:
If the scopes you initially requested have changed, or your users may have otherwise authorized some but not all of those scopes, 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.
If your app needs to remove scopes for a user, you will have to delete all of the user's tokens individually. You can request all tokens authorized for your app, and delete all of them for a user. Once all tokens are removed, the user will have to completely re-authenticate the app, and you can request different scopes.
In the documentation, anscope indicates that an app token is required for the endpoint.
If any other scope is authorized,
basic is redundant.
Because it is redundant, it will be included in the authorization options if any other scope is authorized. If your app is double-checking what scopes were authorized, be sure it does not get thrown off if it sees
Any scope will allow access to any endpoints in the API that specifyaccess token. That includes a user's...
- public clients
as well as abilities to...
- report a post or message
- set a stream marker
- delete user streams
- get your current token
App Streams do not notify of email address changes.
Uploading Files vs Managing Files
Clients that only upload files to attach to posts or messages don't need
files authorized. If you already have
write_post or a
messages scope authorized, you can upload files.
If a client has a
files-related scope, it will be able to retrieve, update, attach, and delete those 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.
Uploading Polls vs Managing Polls
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
write_post allows an app to create files and polls as well, so those can be created and attached using their returned "tokens".