Scopes

Bungie.net offers a range of APIs an application can call, each dipping into different feature areas. For example, a user could use your application to review or modify their profile, post to forums, or groups, review their game play information, transfer items between characters, etc. Many applications will focus on features related to transferring items between characters, or examining a characters inventory. So why bother getting permission from your user to do anything else? Your scope, set in the Bungie.net application portal, declares which APIs you care about so Bungie.net can let the user know what your applications might do. The Access Token your application uses to prove it has permission to call an API on behalf of a user includes this scope and the platform will make sure calls to other APIs are disallowed.

The scope protects your user by letting them have some insight into what an application may do, and it limits the damage that can be done should an Access Token or Refresh Token somehow get stolen. For these reasons, you should choose only the scopes you need.

Scope	Value	Description
ReadBasicUserProfile	1	Read user profile information such as the user's handle, Xbox, Blizzard, and PSN account names, and Destiny characters.
AdminGroups	8	Automate administration of your own Group.
MoveEquipDestinyItems	32	Move or equip Destiny items
ReadDestinyInventoryAndVault	64	Read user's Destiny vault and character inventory.
ReadUserData	128	Read user data such as web notifications, clan/group memberships, recent activity, and muted users.
ReadDestinyVendorsAndAdvisors	512	Access vendor and advisor data specific to a user.

The ReadBasicUserProfile scope is implicitly included in the scope of all applications. It permits a call to GetMembershipForCurrentUser, which is sufficient to determine that a user has control of a particular account. You may configure additional scopes in the portal.

If you change your application’s scope after a user has authorized it, the Refresh Token for that user will still only include the scope that user authorized. To expand (or contract) your scope, you must repeat the authorization flow described at the beginning of this document, thus informing the user of the change. The user must approve all items requested by your scope, so you will not need to worry about some APIs working while others do not.