API Documentation

Working With OAuth

ESO Logs uses OAuth 2.0 for API authentication. OAuth allows clients to request and then use an access token to authenticate API requests. We recommend that developers use stable libraries for performing the OAuth process instead of implementing their own.

When using a library, developers typically need four items to get started: their client_id, client_secret, authorize_uri, and token_uri.

Client ID and Client Secret

The first step in using OAuth is getting a client_id and client_secret by creating a new client.

1. Log in to ESO Logs.
2. Go to the client management page and click Create Client.
3. Enter a client name. The client name is used to identify the client in the list view. Client names will be visible to your site users when authorizing them.
4. Enter any redirect URIs needed. If you need to support multiple redirects you can separate the URLs with commas. Make sure you escape commas within a single URI.
5. Click Create.

OAuth URIs

OAuth requires two commonly-used URIs to work properly. The authorize_uri gets user authorization to allow applications to access certain information, such as the fights and events of a private report. The token_uri submits items, such as authorization codes, to request access tokens applications can use with the v2 API.

The v2 APIs require access tokens granted one of three possible flows: the client credentials flow, the authorization code flow, or the PKCE code flow.

Client Credentials Flow

The client credentials flow is used to access the public API. No user authorization is required in this flow, and only public information is accessible, i.e., no private reports may be accessed.

The APIs under /api/v2/client are accessed using this flow.

In the OAuth client credentials flow, a pair of client credentials (client_id and client_secret) is exchanged for an access token.

To request access tokens, an application must make a POST request with the following multipart form data to the token URI: grant_type=client_credentials

The application must pass basic HTTP auth credentials using the client_id as the user and the client_secret as the password.

After an application retrieves an access token, it provides that token when making requests to API resources. This is done via an authorization header:

curl --header "Authorization: Bearer <access_token>" <GRAPHQL API URL>

If you wish to use the client credentials code flow with a browser-based application (where CORS is an issue), then you will need to have a server that is responsible for obtaining access tokens that can then be used in the browser. If you do not have a server, then you should consider using the PKCE code flow instead.

Authorization Code Flow

The OAuth 2.0 Authorization Code Flow allows an application to access a user's data on their behalf. This allows an application to acquire more sensitive, opt-in information about a user, such as a user's private reports, after obtaining the user's permission to do so. The Authorization Code Flow has two major parts: the authorization code request and the access token request.

The APIs under /api/v2/user are accessed using this flow.

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

To request access tokens, an application needs to provide the following POST parameters to the token URI, using the developer's client ID and secret with HTTP basic authorization:

After an application retrieves an access token, it provides that token when making requests to API resources. This is done via an authorization header:

curl --header "Authorization: Bearer <access_token>" <GRAPHQL API URL>

PKCE Code Flow

The OAuth 2.0 PKCE code flow allows an application to access a user's data on their behalf. This allows an application to acquire more sensitive, opt-in information about a user, such as a user's private reports, after obtaining the user's permission to do so. The PKCE code flow has two major parts: the authorization code request and the access token request.

The APIs under /api/v2/user can be accessed using this flow. The PKCE code flow is used from applications (e.g., browser-based apps) that are not able to securely access a client secret, so a code challenge/verifier is used instead.

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

Both the state and the code verifier should be stored in the session so that the callback can retrieve them.

Example (PHP) of Generating the Code Verifier and Code Challenge

$code_verifier = Str::random(128);
$encoded = base64_encode(hash('sha256', $code_verifier, true));
$codeChallenge = strtr(rtrim($encoded, '='), '+/', '-_');

After the user has granted authorization, the application sends the user back to the redirect_uri site with the state query parameter and a code query parameter. code is the authorization code that represents the user's agreement to allow an application to access their private data.

To request access tokens, an application needs to provide the following POST parameters to the token URI:

curl --header "Authorization: Bearer <access_token>" <GRAPHQL API URL>

GraphQL

The v2 API uses GraphQL. We recommend using the Insomnia client for working with GraphQL. You can set up the Bearer authorization and work inside the app as an API playground.

Viewing Detailed Documentation

GraphQL uses schemas that document everything, so if you use a client like Insomnia, you can fetch the schemas and start browsing the API documentation in the client itself.

Contact Us

As always, we love to hear your feedback. Please join us on Discord to share any feedback and suggestions, or to ask any questions.

Follow our Twitter for updates!

If you have any support questions, please reach out to our support team at [email protected].