App permissions
App permissions describe the access level for application-user authentication. App permissions are configured per application within your Twitter app settings.
There are three levels of permission available:
- read only
- read and write
- read, write and access Direct Messages
An additional permission exists to request visibility of a user’s email address - this can be combined with any of the three levels listed above.
If a permission level is changed, any user tokens already issued to that Twitter app must be discarded and users must re-authorize the app in order for the token to inherit the updated permissions.
A good practice is to request only the minimum level of access to a user’s account data that an application or service requires.
Read only
This permission level permits read access to Twitter resources, including (for example) a user’s Tweets, home timeline, and profile information. It does not allow access to read a user’s Direct Messages.
Read and write
This permission level permits read and write access to Twitter resources, including the ability to read a user’s Tweets, home timeline, and profile information; and to post Tweets, follow users, or update elements of a user’s profile information. It also allows write access to send Direct Messages on behalf of a user (POST direct_messages/events/new) but does not provide the ability to read or delete Direct Messages.
Read, write and access Direct Messages
This permission level includes access to all of the above and adds the ability to read and delete Direct Messages on behalf of a user.
- GET direct_messages/events/show
- GET direct_messages/events/list
- DELETE direct_messages/events/destroy
Additional: Request email address
This additional permission may be combined with any of the other levels. When authorizing a Twitter app, the user will also be informed that the app may request visibility of any email address associated with the account (via the account/verify_credentials endpoint). To use this permission, the app settings must be configured to point to valid privacy policy and terms of service URLs via the app's settings so that users understand the terms under which their email address may be used and stored.
Determining permissions
All authenticated API requests return an `x-access-level header in the HTTP response. The value of the header shows the current permission level of either the access token or bearer token in use. Possible values are read, read-write, and read-write-directmessages.