The Bungie.net application portal will be your first stop in getting setup in order to start making API calls against the Bungie.net platform. This article will focus on explaining the various fields in the application portal and what they represent.

In order to access the application portal you will need to have linked (PSN, XBox or Blizzard) account with Bungie.net. If you have not already done so be sure to do that first before continuing.

You can access the application portal through this link: https://www.bungie.net/en/application

After logging into the portal you will be brought to the landing page that will list any applications that you have along with the ability to create and register a new app with Bungie. In order to create a new app click on the button as seen in the image below.

The first section as seen below is straight forward. You will enter your application name (i.e. what you are calling your application) and the website where Guardians can learn about your application.

In this section you will define how your application will define the authentication your app will use (i.e. the process of the client (your app) proving its identity to the server (Bungie's RESTful web services). In this section we will touch on some concepts as the items below relate to OAuth; however, in the next wiki page we will go in detail. Bungie's implementation of OAuth is built on RFC 6749 The OAuth 2.0 Authorization Framework. When I refer to specification I am specifically referring to RFC 6749.

You have three options to choose from in regards to "OAuth Client Type". They are Public, Confidential and Not applicable.

Not Applicable
You will choose this option if you plan on having no user interaction with your application (i.e. not using OAuth). An example of this would be where you just want to use the API key to get some basic stat information and have no intention of users actually interacting with your application.

If you are planning on having users interact with your application you will want to implement OAuth. OAuth provides a secure way in authorizing users on your applications behalf without the need for directly capturing the users credentials. At the same time this provides limited scopes (i.e. actions) your application can make on the users behalf. Bungie does not support cookie authentication which some are familiar from Destiny 1 before OAuth was implemented by Bungie.

Public
Per RFC 6749 Section 2.1 it states: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.

What this means is that if the client does not run in a secure environment (i.e. a server with secure limited access) then the client should NOT be considered confidential but instead public. Public clients are NOT issued a client secret. However, many times you will see developers classify their application as confidential when it is really public (i.e. mobile/desktop app) that resides on the resource owners device. They do this to avoid having users login every hour since public clients are not issued refresh tokens. The problem with this is that is most cases developers are hard coding their client secret into their application. If it can be compiled it can be decompiled. Even obfuscation can be cracked.

Confidential
Per RFC 6749 Section 2.1 it states: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.

What this means is that the client has a means to run in a secure environment (i.e. a server with secure limited access) where the client secret can remain secure from prying eyes (i.e. only those who should have access to it have access to it).

Security Concerns
Confidential clients are considered more secure than public clients since it is assumed that the client secret is secure. When the client calls the authorization server endpoints and passes their secret it is assumed the client is who they really say they are since no other client should know the secret. With anything though there are always security threats. As such you can read RFC 6819 OAuth 2.0 Threat Model and Security Considerations

After completing its interaction with the resource owner (i.e. the resource owner approves or disapproves of the client acting on its behalf with specified scopes), the authorization server directs the resource owner's user-agent back to the client. This direction back to the client occurs based on the redirection URL that is defined in the portal. Bungie allows for one redirection URL to be specified. The redirection endpoint URI MUST be an absolute URI and is case sensitive. The endpoint URI MAY include an "application/x-www-form-urlencoded" formatted query component which MUST be retained when adding additional query parameters. The endpoint URI MUST NOT include a fragment component.

In addition that redirection URL that is supplied should also use TLS. The specification does not mandate the use of TLS; however, lack of transport-layer security can have a severe impact on the security of the client and the protected resources it is authorized to access.

Scope is where you will select which permissions you want to have users authorize your application with. Scope cannot be dynamically changed by the user when authorizing your application. 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.

For example, if you choose all scopes available but a user only wants to authorize your application to read their inventory and vault along with basic user profile information (which is automatically included) and nothing else they cannot change the scope. They either have to authorize all scopes you have selected in the client registration process or not authorize your application.

As general practice you should only select the scopes that your application currently needs. As you add additional features to your application that require additional scopes you can always edit your registered application to use those scopes. 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. 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. There is an exception this however. If you make use of an API that requires a scope that is not listed in the application portal you must have Bungie manually add this scope to your application in order to make use of that API Endpoint. An example of this would be if you needed access to the AdminGroups scope.

The current scopes as seen in application registration portal are as follows:

Scope	Value	Description	Endpoints
ReadBasicUserProfile	1	Read basic user profile information such as the user's handle, avatar icon, etc.	User.GetMembershipDataForCurrentUser
MoveEquipDestinyItems	32	Move or equip Destiny items	Destiny2.TransferItem Destiny2.PullFromPostmaster Destiny2.EquipItem Destiny2.EquipItems Destiny2.SetItemLockState Destiny2.InsertSocketPlug Destiny2.ActivateTalentNode
ReadDestinyInventoryAndVault	64	Read Destiny 1 Inventory and Vault contents. For Destiny 2, this scope is needed to read anything regarded as private. This is the only scope a Destiny 2 app needs for read operations against Destiny 2 data such as inventory, vault, currency, vendors, milestones, progression, etc.
ReadUserData	128	Read user data such as who they are web notifications, clan/group memberships, recent activity, muted users.	GroupV2.GetUserClanInviteSetting
ReadDestinyVendorsAndAdvisors	512	Access vendor and adviser data specific to a user. OBSOLETE. This scope is only used on the Destiny 1 API.

Modern web browsers implement Same-Origin Policy in order to restrict malicious scripts from accessing sensitive data on another web page through the Document Object Model (DOM). Under the same-origin policy web page A can only access web page B if they are of the same origin. This is handled by the browser through the Origin Header. The Origin represents where the fetch originated from. Unlike the Referer Header which discloses the full path the Origin Header does not disclose the whole path but rather than following: <scheme> "://" <host> [ ":" <port> ].

An example would be if https://www.server-a.com/index.html made a request to https://www.server-b.com/HelloWorld.html. It would fail under the same-origin policy because Origin: https://www.server-a.com does not match Origin: https://www.server-b.com

In order to get around this limitation Cross-Origin Resource Sharing (CORS) was created to use additional headers to let a user agent request resources from another server with a different origin while still protecting the user from malicious scripts. While newer web browsers have built in support to handle adding the additional headers for a CORS request it is up the server hosting the resource in the other domain to implement the functionality to handle CORS request. In many cases you will see the request issued twice if you are watching the request in your browsers developer tools or another external tool like fiddler. The first request is an OPTIONS or "preflight" request where the request is sent to the server with the resources trying to be accessed to make sure the request is supported and meets all the required criteria. If it does then the actual request with the actual HTTP request method is sent. As with the same-origin policy the 'Origin' header in the CORS request follows the format <scheme> "://" <host> [ ":" <port> ] and is handled by the browser. The server where the resource is being hosted and the request sent will then reply with the Access-Control-Allow-Origin header. If the server specifies an origin host rather than the wildcard "*", then it must also include Vary: Origin in the response header to indicate to clients that server responses will differ based on the value of the Origin request header.

Based on this high level overview we are now ready to enter our origin value(s) in the Bungie application portal.

Per Bungie:

Bungie.net requires that if a platform request contains an origin header that it match the origin header registered with the application as determined by the API key in that request. If there is not a match, or the origin has not been configured for the application the request will be rejected.

This is a defense in depth measure that narrows the usefulness of an API key. Since web browsers should add the origin header outside of the control of the application, an API key used in a context where it was not intended will not work. For example, if the key is accidentally copied from a source code repository, or taken from another application. There is a long list of cases where this measure has no impact, and so it is far from a thorough security feature.

Application developers that are hindered by the origin header either because the value of the header is unpredictable due to some nuance of the platform they are using, or they have a few different origin values possible may do one of the following in the Bungie.net application portal:

Configure the value of the origin to "" (without the quotes) Provide a comma separated list of origin values (up to 200 characters total). The "" option provides the most flexibility, but makes the API key easier to use in unintended contexts. Specifying a single specific origin or a short list of valid origins is preferred.

Before creating your app you must check the I agree to abide by the Terms of Use for the Bungie.net API box. You can find the terms of use here: Bungie.net Terms of Use

After you have successfully created your application through the Bungie.net application portal you will be taken the application details page. This page will look exactly like the one from when you created your application with the exception of the now added API Keys section which will will contain the necessary information for application to submit successfully request.

Upon initial application creation you will automatically be assigned one API key but may possess up to twp API keys per application. For each API key that you have obtained you have the options of enabling, disabling and deleting the key. This is useful in situations where you need to test break fixes or your key has been accidentally leaked for example.

This is the redirection URL that you will use to authorize your client (app) for a user. This is the first step in the OAuth flow.

This is the ID that Bungie has assigned to your application that uniquely identifies it. Your client ID is tied to your application settings in the Bungie.net Application Portal.

If your application is using the OAuth workflow and has been classified as confidential you will be issued a client secret which will be used in the OAuth Authorization workflow.

Application's that are Private or Public can have a status of Active, Disabled or Blocked. controlling the status of your application as to whether it is Active or Disabled is up to the application owner.

Per Bungie:

Blocked is reserved for applications that have misbehaved in some way and need to be taken out of circulation. Only Bungie can change an application to the Blocked state. Once blocked, an application will no longer work with Bungie.net and the application may not be edited by its originator. Only Bungie may unblock an application. This will be used in exceedingly rare cases and should not be a concern to any well-meaning application developers.

Every write operation your application performs is kept in an activity log that may be inspected by the affected user. This helps the user understand what your application is doing even if it was done without direct user interaction. The activity log is accessible from the user’s profile settings under Accounts & Linking. A user may also revoke access previously granted to your application from this page. This revocation will take place the next time your application attempts to get a new Access Token from a Refresh Token. This can be reversed by taking the user back through the Authorization flow.