Application Permission Model

Overview

There are three levels of permission available to applications:

  1. read only
  2. read and write
  3. 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.

Application permissions are configured using the dashboard at apps.twitter.com. If a permission level is changed, any user tokens already issued must be discarded and the user must re-authorize the application 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 does not allow access to read or send Direct Messages.

Read, write and access Direct Messages

This permission level adds the ability to read and send Direct Messages on behalf of a user.

Additional: Request email address

This additional permission may be combined with any of the other levels. When authorizing an application, the user will also be informed that the application may request visibility of any email address associated with the account (via the account/verify_credentials endpoint). To use this permission, the application settings must be configured to point to valid privacy policy and terms of service URLs via apps.twitter.com 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 the access token in use. Possible values are read, read-write, and read-write-directmessages.