Using OAuth


Important: You must update your integration by January 6, 2019.

We have launched a new Developer Portal to enhance our offering to community developers. In order to maintain service, please read our migration guide.


The Blizzard APIs uses OAuth 2.0, a federated access control mechanism, to help secure sections of the APIs that we provide out to the public. By using OAuth, you can let Blizzard handle the authentication process and receive a unique ID representing that user, then use an access token to gain access to allowed resources like their World of Warcraft characters, StarCraft II profile, or other data as appropriate. The usage of OAuth itself is relatively simple, but the flows can seem a little intimidating at first. Hopefully, by following the processes below, you can quickly integrate with Blizzard's OAuth and worry more about building that cool idea and less about how to get data from players.

Note, due to the sensitive nature of storing user data, it is HIGHLY RECOMMENDED that you use stable libraries for performing the OAuth process instead of implementing your own. If we suspect that your site has been compromised or see suspicious activity regarding your project, all access tokens and authorizations for your client will be removed and your client ID could be permanently revoked.

Sample Libraries

For many OAuth 2.0 libraries you only need the data below (OAuth URLs) and your key and secret from your application registration. Some platforms also make use of plugins that come preset with both the URLs and ability to get some profile information about the user. We have prepared two sample libraries that the community can use for Ruby and Node web apps:

Library Quick Start

If you're using a library, there should mainly only be four items that you'll typically need to get started. Those are a client_id, client_secret, authorize_uri and token_uri.

Client ID and Secret

The first step in using OAuth is getting a client_id. If you head on over to the registration page, you can complete the registration process, which will provide you with a client_id and client_secret. If using a library, you should be able to plug those values into it, and begin working. Please note that your application Key is the client_id and the Secret is the client_secret.

Redirect URL

When registering an application you can specify a redirect url for that key. This must be a valid HTTPS (SSL-enabled) URL. After a user authorizes themselves on Blizzard's login page we will only redirect them back to this URL.

OAuth URIs

In order for OAuth to work properly, there are a couple of URIs that are commonly used. The authorize_uri is used to get player authorization for you to access certain resources of theirs, like a list of Diablo III characters. The token_uri is used to turn in items (like an authorization code) for access tokens that you can then use with any of our APIs. Those values are:

Region Authorize URI Token URI
US, EU, APAC https://<region> https://<region>

Where the <region> is one of the following: us, eu, or apac. APAC is short for Asia-Pacific and replaces the previous kr and tw regions. In order to use OAuth on the SEA SC2 community API, you should use the US OAuth servers.

There is also a check_token endpoint available to check the details of a token. It is available in all regions at /oauth/check_token?token=<token>. This can be used to verify that an access token actually was generated for your client.

There is also a check_token endpoint available to check the details of a token. It is available in all regions at /oauth/check_token?token=<token>. This can be used to verify that an access token actually was generated for your client.

Scopes and OAuth enabled APIs

Scopes are used to request specific information from a user of your site. You don't need to request any scopes to use Blizzard login. Without scopes, you will get access to a users account ID and BattleTag. To get any more specific user information you'll need to request it from the user using scopes.

Right now we only have two scopes that are able to be requested:

Scope Description Example API URL
wow.profile Access to a users World of Warcraft characters
sc2.profile Access to a users StarCraft II profile

Access Tokens

Our access tokens last for 30 days. Access tokens may expire before 30 days in specific cases. A user changing their password, removing the authorization for your account, or getting their account locked for any reason will result in the expiration of their current access tokens. Always check the response and request a new access token if your current one fails to work.

The Details

If you do decide to implement an OAuth client yourself, or are just interested in the general flow of OAuth, here is the process in more detail:

# Authorization Code Server Flow

The Authorization Code server flow is the most common flow and represents a client (that's you!) attempting to access the data of a player on behalf of that player. This allows you to get details around a player, such as their World of Warcraft characters, without having to go through a clunky UI where they do things like fill in server and character names. It has two major parts, the Authorization Code request, and the access token request.

For an authorization code request, you need to either redirect the browser or open a new window to the authorize URI with the following query parameters:

Term Description
client_id The client id given to you upon registration.
scope The space separated scope values you wish to request from the player.
state A semi-random data blob to be sent back along with the player when completing authorization.
redirect_uri The location to redirect the user to. Should either be https://localhost for testing or the redirect_uri configured when signing up.
response_type The code type being requested. For the authorization code server flow, this should be code

Once the player has granted authorization, they will be directed back to the site listed at redirect_uri along with the state query parameter and a query parameter called code. This is the authorization code that represents the user's agreement to allow you data. Note, however, that users can fine tune what data they wish for you to view, so the authorization may not encompass all of the scopes you requested. You should parse this token and prepare to request access tokens from it.

To request access tokens, you need to provide the following POST parameters to the token URI, using your client ID and secret with HTTP Basic Authorization:

Term Description
redirect_uri The same redirect_uri used when obtaining the authorization.
scope The scopes you need for the access token. Note that this can be less than the authorization.
grant_type authorization_code.
code The code for the specific grant_type used.

The server should respond with a JSON structure that contains an access token. From there, you should be able to use the access token to access any of the allowed resources on behalf of that player! You can refer to any of the game API pages to learn about what data you can request.

# Client Credentials Flow

The Client Credentials Flow is used to exchange a pair of client credentials (client_id & client_secret) for a access token.

Retrieving an Access Token

To request access tokens, you will need to make a GET request with the following query parameters to the token URI.

Query parameter Description
grant_type client_credentials.
client_id The client_id of a registered application.
client_secret The corresponding client_secret for the client_id of a registered application.

Example curl request:

curl \
'<client_id>&client_secret=<client_secret>' \
-H 'Accept: application/json'

Expected responses:

Response Type Example
Success { "access_token": <string>, "token_type": "bearer", "expires_in": <integer> }
Error { "error": <string>, "error_description": <string> }

Using an Access Token

Once you have retrieved an access token you can provide that token when making requests to API resources. This can be done via a query parameter, or via an Authorization header.

Method Example
Query parameter ?access_token=<token>
Authorization Header Authorization: Bearer <token>

Security Considerations

When dealing with OAuth, there are several steps that you should take in order to ensure that you don't accidentally leak client information or have a potential security hole. We'll detail each one, in order through the system.


One of the major changes to OAuth when releasing version 2.0 was removing transport considerations from the protocol, instead relying on implementors to handle the transport of codes and tokens themselves. What this means in practical terms is that HTTPS is required, and for extra security, checking the cert during the HTTPS handshake is recommended. This will prevent any surprises and will prevent the codes from being captured while in transit.

State Parameter

When requesting an authorization code (by directing the player to, one of the parameters you should pass is the state parameter. To us, this is an opaque blob but should be semi-random to help prevent cross-site scripting attacks. Otherwise, an evil hacker could direct someone to us, who direct to you, which causes you to do some action that the user didn't actually request. In addition, since the data is sent back to you untransformed, this can be used as a way for you to manage multiple redirect locations...but if not properly secured, could be used to redirect a user to a phishing site or other evil purpose because the redirect location wasn't checked.

Client Secret

Understand that the only time the client secret should be sent to us is as part of exchanging the authorization code for an access token, and should always be sent as part of a POST operation

Access Token

Access tokens are all-access passes to player data, and as such, should be handled very closely. They should never be sent out to the player in any format, and should only be used server side. In addition, if an attacker compromises your site, those tokens can be used to glean details about players that none of us want to divulge. An access token only lives for about 30 days, so if you are doing an operation that doesn't require constant access, making a single request to get that data and never storing the token allows for the safest use of our APIs.

Learning More

If you wish to learn more about OAuth 2.0, the next step is to look at the official RFC, located here