Path of Exile Developer Docs

Authorization

Almost all of Path of Exile's developer APIs require authorization of an existing Path of Exile account to use. This helps us enforce fair rate-limits as well as having a point of contact if anything goes wrong.

For this purpose we use an implementation of the OAuth 2 framework along with some key extensions. This document will describe how to generate access tokens for users using your application's credentials.

OAuth 2

OAuth is a popular and common way for an application to act in limited ways on behalf of a user. There are many resources online documenting the basic idea as well as frameworks that can help you understand how the process works. For this reason our implementation closely follows the original specification (RFC 6749).

Implementation Decisions

We support three grant types; the authorization code grant, the client credentials grant, and the refresh token grant. Your application may be restricted on which of these it can access. We do not support the implicit grant or the PKCE (proof key for code exchange) extension. This means that any distributed application (one that runs on a user's machine) will need to be backed by a secure server in order to keep your application credentials secret.

We enforce the use of the state parameter. This is not optional and must be unique for each URL generated for the authorization code grant flow.

We allow partial redirect URIs to be registered, but do require it be sent in during token exchange. We do not allow using "localhost" as a redirect URI.

Access tokens that we generate will last for 28 days. Refresh tokens last for 90 days. Users can review and revoke their tokens on their profile's applications page at any time.

OAuth Server Endpoints

Grant Types

Authorization Code Grant

This grant is used when your application needs access to act on another user's behalf. All authentication is done by the Path of Exile's OAuth server and no user credentials are ever shared or exchanged. The most important step is sending the user to the authorization page which presents them with the details of your request.

Flow:

  1. Generate an authorization URL and allow the user to navigate to it:
    https://www.pathofexile.com/oauth/authorize
        ?client_id=example
        &response_type=code
        &scope=account:profile
        &state=10ceb8104963e91e47a95f4138448ecf
        &redirect_uri=https://example.com
        &prompt=consent
    
    • client_id is your registered application's client id.
    • response_type is always code.
    • scope is a space-separated list of requested scopes.
    • state is a code or hash that you generate to validate the request.
    • redirect_uri is the URL that you want the result of the authorization request to be sent to.
    • prompt can either be consent (the default) or none:
      • consent will ask the user for consent after making sure they're logged in.
      • none will attempt to re-authorize the request with existing consent. If this is not possible then an error response is immediately returned without the user being prompted.

    On success the user will be redirected to your redirect_uri with a code and the state as query parameters.
    On failure the user will also be redirected to your redirect_uri with details according to Section 4.1.2.1.
  2. Check that the state parameter matches one that you have generated. This helps ensure that the request comes from your application.
  3. Exchange the code for an access token using your application's credentials.
    Send a POST request to /oauth/token like in the following example:
    POST https://www.pathofexile.com/oauth/token
    ...
    Content-Type: application/x-www-form-urlencoded
     client_id=example &client_secret=verysecret &grant_type=authorization_code &code=d25cc653854f1d4db9c0797a30a374c6 &redirect_uri=https://example.com &scope=account:profile
    Authorization codes only last for 30 seconds, so make sure to exchange them quickly!
    On success you will receive a response with an access and refresh token for the user:
    {
        "access_token": "486132c90fedb152360bc0e1aa54eea155768eb9",
        "expires_in": 2592000,
        "token_type": "bearer",
        "scope": "account:profile",
        "refresh_token": "17abaa74e599192f7650a4b89b6e9dfef2ff68cd"
    }

Client Credentials Grant

This grant can be used by an application in order to access services unrelated to an individual account that are exposed as part of the Path of Exile API. Unlike other tokens these ones do not have a set expiration time. They can still be revoked manually via your application settings page.

Flow:

  1. Submit a request for a token using the client_credentials grant:
    Send a POST request to /oauth/token like in the following example:
    POST https://www.pathofexile.com/oauth/token
    ...
    Content-Type: application/x-www-form-urlencoded
     client_id=example &client_secret=verysecret &grant_type=client_credentials &scope=service:psapi
    On success you will receive a response with an access token:
    {
        "access_token": "cded8a4638ae9bc5fe6cd897890e25e41f0f4e21",
        "expires_in": null,
        "token_type": "bearer",
        "scope": "service:psapi"
    }
    Please note: tokens generated via the Client Credentials method have their identity set to the registered owner of the application. This means that tokens with appropriate scopes will have access your account details. It is extremely important that you keep your client credentials a secret. The owning account will also be used for rate-limiting endpoints where appropriate.

Refresh Token Grant

If your application has access to the refresh token grant type then you will receive an additional refresh_token property at the final step of the authorization code grant. This token lasts for 90 days and can be used to generate a new access token without requesting the user's consent again.

Flow:

  1. Submit a request for a token using the refresh_token grant:
    Send a POST request to /oauth/token like in the following example:
    POST https://www.pathofexile.com/oauth/token
    ...
    Content-Type: application/x-www-form-urlencoded
     client_id=example &client_secret=verysecret &grant_type=refresh_token &refresh_token=17abaa74e599192f7650a4b89b6e9dfef2ff68cd
    On success you will receive a response with an access token:
    {
        "access_token": "41bcefbc2f0d6ea0fa1cce10c435310d3c475e5b",
        "expires_in": 2592000,
        "token_type": "bearer",
        "scope": "account:profile"
    }

Authorizing a Request

Once you have an access token, all you need to do is include it in the Authorization header of a request:

Authorization: Bearer 486132c90fedb152360bc0e1aa54eea155768eb9

An HTTP 401 error will occur when the token has expired or has been revoked. You will need to generate a new one.

Similarly, an HTTP 403 error occurs when using a token that does not have the correct scope for the resource. You will need to generate a new one with the correct scopes set.

Managing Tokens

As access tokens allow access to a specific user's personal information, you must be careful in how you store them. You must not share access tokens with anyone but their owner. Since they do eventually expire it's fine to send them to the browser to store client-side in a Cookie or local storage as long as you do so using a secure method such as HTTPS.

Refresh tokens must always be stored in a secure manner server-side. If your application flow does not allow for this then refresh tokens can be turned off for your application to meet our requirements.

Available Scopes