Custom API scopes for GraphQL mutations

Release notes

The API scopes we can give to tokens are very broad - basically either read_api or api. It is impossible to limit a token to one particular function, and limit abuse beyond that.

We can introduce custom scopes, such as api:graphql:mutate:{mutation-name}. An example would be api:graphql:mutate:createNote. These scopes would only be valid for the named GraphQL mutation.

Problem to solve

Users want to automate things, and this means delegating authority to act. But handing out personal access tokens exposes the user to risks if the token is compromised.

We can limit this if tokens are narrowly scoped to their intended task. That would mean an integration designed to add notes could not then perform other actions (such as deleting data, or merging code).

Intended users

All users who provide tokens to 3rd party integrations, but especially:

User experience goal

Users can authorize OAuth applications in confidence and hand out tokens knowing they cannot be used to execute unanticipated actions.

Proposal

We introduce new scopes, which include the name of the Mutation they are authorized to execute.

In BaseMutation.authorize? we then check that the user token has either api or this narrow scope.

When a user authorizes an OAuth application, we should display the list of actions it requests

When a user creates a PAT, we supply a list of mutations so users can select an appropriate one.

Further details, open questions

How should this interact with api? If a token has api scope, and a mutation scope, how should we proceed?

Should we introduce a rest_api scope to deal with that

Permissions and Security

This would affect all tokens.

Documentation

We would need new user documentation explaining the token scopes and how and why to use them.

Availability & Testing

Available Tier

Undecided. This would make a good premium+ feature

What does success look like, and how can we measure that?

Success if when a user can issue a token that cannot be used for unanticipated purposes

What is the type of buyer?

Security and compliance orientated organizations.

Is this a cross-stage feature?

This would affect API usage, and GraphQL usage in particular. It would need awareness across the organization.