I know that I can grant permission of an application to do something with my account on the network. What can and cannot an application do if I allow it? For example, if I see a description like:
- Identify your account
- Access your private actions and information
- Create and change content on your behalf
- Read your global inbox
- Keep these permissions perpetually
How can I figure out exactly what this encompasses?
The Stack Exchange API offers a number of things an application can do. This description is going to be light on technical details as those can be looked up in the documentation. However, we still need to cover the basics:
The API can be used anonymously but with limitations. An application can ask to be authorised which will soften these limitations. The authorisation allows it to act as a given user. This can help with traceability of actions but also can open up new actions that could not be used anonymously.
An application can ask a user to authorise it. This is an explicit action where the user will need to confirm.
Authorisations come with scopes. Each time an application asks for access, it has to explicitly list which scopes it wants access to. This could also be none (which limits the amount of things that can be done). The scopes are:
Which action requires which scope (if any) is documented further down.
1 from the API documentation 2 only documented at individual actions
Access to an application will be limited in time unless the no_expiry grant is requested. With it, the access will be perpetual.
As a user, you can always revoke access you have given to an application:
From here you can de-authorise any application you have have used at any point.
An application can request write access at which point it will be able to do actions in the user's name. For example, posting or flagging will require write access.
This can be dangerous, so accept it with caution.
However, do keep in mind the following:
This is information available from the overview as well as the detailed information for each method. Formatted as a single table for convenience.
| API endpoint | Description | Authorisation required? | Scope required |
|---|---|---|---|
| answers | Get all answers on the site. | - | - |
| answers/{ids} | Get answers identified by a set of ids. | - | - |
| answers/{id}/accept | Casts an accept vote on the given answer. | auth required | write_access |
| answers/{id}/accept/undo | Undoes an accept vote on the given answer. | auth required | write_access |
| answers/{ids}/comments | Get comments on the answers identified by a set of ids. | - | - |
| answers/{id}/delete | Deletes the given answer. | auth required | write_access |
| answers/{id}/downvote | Casts a downvote on the given answer. | auth required | write_access |
| answers/{id}/downvote/undo | Undoes a downvote on the given answer. | auth required | write_access |
| answers/{id}/edit | Edits the given answer. | auth required | write_access |
| answers/{id}/flags/options | Returns valid flag options for the given answer. | auth required | - |
| answers/{id}/flags/add | Casts a flag on the given answer. | auth required | write_access |
| answers/{ids}/questions | Gets all questions the answers identified by ids are on. | - | - |
| answers/{id}/upvote | Casts an upvote on the given answer. | auth required | write_access |
| answers/{id}/upvote/undo | Undoes an upvote on the given answer. | auth required | write_access |
| answers/{id}/recommend | Casts a recommendation on the given answer. | auth required | write_access and manage_collective_recommendations |
| answers/{id}/recommend/undo | Undoes an recommendation on the given answer. | auth required | write_access and manage_collective_recommendations |
| answers/{id}/suggested-edit/add | Creates a suggested edit on an existing answer. | auth required | write_access |
| badges | Get all badges on the site, in alphabetical order. | - | - |
| badges/{ids} | Get the badges identified by ids. | - | - |
| badges/name | Get all non-tagged-based badges in alphabetical order. | - | - |
| badges/recipients | Get badges recently awarded on the site. | - | - |
| badges/{ids}/recipients | Get the recent recipients of the given badges. | - | - |
| badges/tags | Get all tagged-based badges in alphabetical order. | - | - |
| collectives | Get all Collectives on the site, in alphabetical order. | - | - |
| collectives/{slugs} | Get Collectives identified by a set of slugs. | - | - |
| collectives/{slugs}/questions | Get questions identified by a set of slugs. | - | - |
| collectives/{slugs}/answers | Get answers identified by a set of slugs. | - | - |
| collectives/{slugs}/tags | Get tags identified by a set of slugs. | - | - |
| collectives/{slugs}/users | Get users identified by a set of slugs. | - | - |
| collectives/{slugs}/reports | Get reports identified by a set of slugs. | auth required | manage_collective_reports|{slug} |
| collectives/{slugs}/reports/add | Creates a new report request for the Collective | auth required | - |
| comments | Get all comments on the site. | - | - |
| comments/{ids} | Get comments identified by a set of ids. | - | - |
| comments/{id}/delete | Delete a comment identified by its id. | auth required | write_access |
| comments/{id}/edit | Edit a comment identified by its id. | auth required | write_access |
| comments/{id}/flags/add | Casts a flag on the given comment. | auth required | write_access |
| comments/{id}/flags/options | Returns valid flag options for the given comment. | auth required | - |
| comments/{id}/upvote | Casts an upvote on the given comment. | auth required | write_access |
| comments/{id}/upvote/undo | Undoes an upvote on the given comment. | auth required | write_access |
| events | Get recent events that have occurred on the site. Effectively a stream of new users and content. | auth required | - |
| info | Get information about the entire site. | - | - |
| posts | Get all posts (questions and answers) in the system. | - | - |
| posts/{ids} | Get all posts identified by a set of ids. Useful for when the type of post (question or answer) is not known. | - | - |
| posts/{ids}/comments | Get comments on the posts (question or answer) identified by a set of ids. | - | - |
| posts/{id}/comments/add | Create a new comment on the post identified by id. | auth required | write_access |
| posts/{id}/comments/render | Renders a hypothetical comment on the given post. | - | - |
| posts/{ids}/revisions | Get revisions on the set of posts in ids. | - | - |
| posts/{ids}/suggested-edits | Get suggested edits on the set of posts in ids. | - | - |
| privileges | Get all the privileges available on the site. | - | - |
| questions | Get all questions on the site. | - | - |
| questions/{ids} | Get the questions identified by a set of ids. | - | - |
| questions/{ids}/answers | Get the answers to the questions identified by a set of ids. | - | - |
| questions/{id}/answers/add | Creates an answer on the given question. | auth required | write_access |
| questions/{id}/answers/render | Renders a hypothetical answer to a question. | - | - |
| questions/{id}/close/options | Returns valid flag options which are also close reasons for the given question. | auth required | - |
| questions/{ids}/comments | Get the comments on the questions identified by a set of ids. | - | - |
| questions/{id}/delete | Deletes the given question. | auth required | write_access |
| questions/{id}/downvote | Casts a downvote on the given question. | auth required | write_access |
| questions/{id}/downvote/undo | Undoes a downvote on the given question. | auth required | write_access |
| questions/{id}/edit | Edits the given question. | auth required | write_access |
| questions/{id}/favorite | Bookmarks the given question. (Previously known as "favoriting" a question) | auth required | write_access |
| questions/{id}/favorite/undo | Undoes bookmarking the given question. (Previously known as "favoriting" a question) | auth required | write_access |
| questions/{id}/flags/add | Casts a flag on the given question. | auth required | write_access |
| questions/{id}/flags/options | Returns valid flag options for the given question. | auth required | - |
| questions/{ids}/linked | Get the questions that link to the questions identified by a set of ids. | - | - |
| questions/{ids}/related | Get the questions that are related to the questions identified by a set of ids. | - | - |
| questions/{id}/suggested-edit/add | Creates a suggested_edit on an existing question. | auth required | write_access |
| questions/{ids}/timeline | Get the timelines of the questions identified by a set of ids. | - | - |
| questions/{id}/upvote | Casts an upvote on the given question. | auth required | write_access |
| questions/{id}/upvote/undo | Undoes an upvote on the given question. | auth required | write_access |
| questions/add | Creates a new question. | auth required | write_access |
| questions/featured | Get all questions on the site with active bounties. | - | - |
| questions/no-answers | Get all questions on the site with no answers. | - | - |
| questions/render | Renders a hypothetical question. | auth required | - |
| questions/unanswered | Get all questions the site considers unanswered. | - | - |
| questions/unanswered/my-tags | Get questions the site considers unanswered within a user's favorite or interesting tags. | auth required | - |
| revisions/{ids} | Get all revisions identified by a set of ids. | - | - |
| search | Search the site for questions meeting certain criteria. | - | - |
| search/advanced | Search the site for questions using most of the on-site search options. | - | - |
| similar | Search the site based on similarity to a title. | - | - |
| search/excerpts | Searches a site. | - | - |
| suggested-edits | Get all the suggested edits on the site. | - | - |
| suggested-edits/{ids} | Get the suggested edits identified by a set of ids. | - | - |
| tags | Get the tags on the site. | - | - |
| tags/{tags}/info | Get tags on the site by their names. | - | - |
| tags/moderator-only | Get the tags on the site that only moderators can use. | - | - |
| tags/required | Get the tags on the site that fulfill required tag constraints. | - | - |
| tags/synonyms | Get all the tag synonyms on the site. | - | - |
| tags/{tags}/faq | Get frequently asked questions in a set of tags. | - | - |
| tags/{tags}/related | Get related tags, based on common tag pairings. | - | - |
| tags/{tags}/synonyms | Get the synonyms for a specific set of tags. | - | - |
| tags/{tag}/top-answerers/{period} | Get the top answer posters in a specific tag, either in the last month or for all time. | - | - |
| tags/{tag}/top-askers/{period} | Get the top question askers in a specific tag, either in the last month or for all time. | - | - |
| tags/{tags}/wikis | Get the wiki entries for a set of tags. | - | - |
| users | Get all users on the site. | - | - |
| users/{ids} | Get the users identified by a set of ids. | - | - |
| users/{ids}/answers | Get the answers posted by the users identified by a set of ids. | - | - |
| users/{ids}/badges | Get the badges earned by the users identified by a set of ids. | - | - |
| users/{ids}/comments | Get the comments posted by the users identified by a set of ids. | - | - |
| users/{ids}/comments/{toid} | Get the comments posted by a set of users in reply to another user. | - | - |
| users/{ids}/favorites | Get the questions bookmarked (previously known as "favorited") by users identified by a set of ids. | - | - |
| users/{ids}/mentioned | Get the comments that mention one of the users identified by a set of ids. | - | - |
| users/{id}/network-activity | Gets a user's activity across the Stack Exchange network. | - | - |
| users/{id}/notifications | Get a user's notifications. | - | read_inbox |
| users/{id}/notifications/unread | Get a user's unread notifications. | - | read_inbox |
| users/{ids}/posts | Get all posts (questions and answers) owned by a set of users. | - | - |
| users/{id}/privileges | Get the privileges the given user has on the site. | - | - |
| users/{ids}/questions | Get the questions asked by the users identified by a set of ids. | - | - |
| users/{ids}/questions/featured | Get the questions on which a set of users, have active bounties. | - | - |
| users/{ids}/questions/no-answers | Get the questions asked by a set of users, which have no answers. | - | - |
| users/{ids}/questions/unaccepted | Get the questions asked by a set of users, which have at least one answer but no accepted answer. | - | - |
| users/{ids}/questions/unanswered | Get the questions asked by a set of users, which are not considered to be adequately answered. | - | - |
| users/{ids}/reputation | Get a subset of the reputation changes experienced by the users identified by a set of ids. | - | - |
| users/{ids}/reputation-history | Get a history of a user's reputation, excluding private events. | - | - |
| users/{id}/reputation-history/full | Get a full history of a user's reputation. | auth required | private_info |
| users/{ids}/suggested-edits | Get the suggested edits provided by users identified by a set of ids. | - | - |
| users/{ids}/tags | Get the tags that the users (identified by a set of ids) have been active in. | - | - |
| users/{id}/tags/{tags}/top-answers | Get the top answers a user has posted on questions with a set of tags. | - | - |
| users/{id}/tags/{tags}/top-questions | Get the top questions a user has posted with a set of tags. | - | - |
| users/{id}/tag-preferences | Get a given user's tag preferences. | auth required | private_info |
| users/{id}/tag-preferences/edit | Edit a user's tag preferences. | auth required | write_access and private_info |
| users/{ids}/timeline | Get a subset of the actions of that have been taken by the users identified by a set of ids. | - | - |
| users/{id}/top-answer-tags | Get the top tags (by score) a single user has posted answers in. | - | - |
| users/{id}/top-question-tags | Get the top tags (by score) a single user has asked questions in. | - | - |
| users/{id}/top-tags | Get the top tags (by score) a single user has posted in. | - | - |
| users/moderators | Get the users who have moderation powers on the site. | - | - |
| users/moderators/elected | Get the users who are active moderators who have also won a moderator election. | - | - |
| users/{id}/inbox | Get a user's inbox. | auth required | read_inbox |
| users/{id}/inbox/unread | Get the unread items in a user's inbox. | auth required | read_inbox |
| access-tokens/{accessTokens}/invalidate | Allows an application to dispose of access_tokens when it is done with them. | - | - |
| access-tokens/{accessTokens} | Allows an application to inspect access_tokens it has, useful for debugging. | - | - |
| users/{id}/achievements | Get a user's recent network-wide achievements. | auth required | - |
| apps/{accessTokens}/de-authenticate | Allows an application to de-authorize itself for a set of users. | - | - |
| errors | Get descriptions of all the errors that the API could return. | - | - |
| errors/{id} | Simulate an API error for testing purposes. | - | - |
| filters/create | Create a new filter. | - | - |
| filters/{filters} | Decode a set of filters, useful for debugging purposes. | - | - |
| inbox | Get a user's inbox, outside of the context of a site. | auth required | read_inbox |
| inbox/unread | Get the unread items in a user's inbox, outside of the context of a site. | auth required | read_inbox |
| notifications | Get a user's notifications, outside of the context of a site. | auth required | read_inbox |
| notifications/unread | Get a user's unread notifications, outside of the context of a site. | auth required | read_inbox |
| sites | Get all the sites in the Stack Exchange network. | - | - |
| users/{ids}/associated | Get a user's associated accounts. | - | - |
| users/{ids}/merges | Get the merges a user's accounts has undergone. | - | - |
- Identify your account
It will require you, as a user, to authenticate the application.
- Access your private actions and information
The application will request the private_info scope.
- Create and change content on your behalf
The application will request the write_access scope.
- Read your global inbox
The application will request the read_inbox scope.
- Keep these permissions perpetually
The application will request the no_expiry scope, thus can keep this access until it is revoked.
