Skip to content

Quick Version

This page is for developers who already know what OAuth 2.0 is, and are just looking for information on the endpoints and supported flows.

OAuth 2.0 endpoints

Supported flows

  • Authorization code flow with mandatory PKCE. This is the only flow available to server-side and website apps, and recommended for mobile apps.
  • Device flow with optional PKCE. Only verification_uri_complete is returned, not verification_uri, as the intended use case for the device flow is Dalamud plugins, which can open URLs in the browser themselves.

Registering apps

Apps are registered at the My OAuth Apps page, which is available to users who have verified their email address and at least one character.

There are three app types:

  • Server-Side: Backend with a web endpoint, capable of protecting its secrets (examples: Node.js, ASP.NET, Java, PHP). These apps are issued a client secret and can only use the authorization code flow. They must register at least one redirect URI.
  • Website: A JavaScript front-end app that uses an API (examples: Angular, React, Vue). These apps do not have a client secret and can only use the authorization code flow. They must register at least one redirect URI.
  • Native: A desktop or mobile application (examples: Android, iOS, Windows Forms, Dalamud plugin). These apps can enable the authorization code flow or the device flow, or both. They have no client secret and are not required to have a redirect URI if they only use the device flow.

The app's client_id is a UUID.

The app's client_secret is generated for server-side apps only, shown only once, and can be regenerated at any point.

Requestable scopes

The Central Archives API doesn't have a fixed set of requestable scopes; rather, it supports six fixed requestable scopes and two scope formats for requesting access to specific characters.

Core OAuth

  • offline_access: return a refresh token. By default, only an access token (valid for two hours) is returned.

Identity API

  • idp:character:?.read: read access to one character of the user's choice (chosen by the user on the consent screen).
  • idp:character:<lodestoneId>.read: read access to the character with the given Lodestone ID. Example: idp:character:37681922.read.
  • idp:character:<World>/<Firstname_Lastname>.read: read access to the character with the given name and world. The space in the character name should be replaced with an underscore. Example: idp:character:Omega/Vielle_Janlenoux.read.
  • idp:character:all.read: read access to all characters on the user account.
  • idp:user.read: read access to basic user information.
  • idp:user:email.read: read access to user email; if an app requests this scope, it MUST also request idp:user.read.

Roleplay API

  • rp:character-profile:all.write: write access to roleplay profiles by character name + world.

Wildcard scopes

Wildcard scopes like idp:character:?.read can be requested, but will never be returned as granted scopes. If a wildcard scope is requested and the request is granted, the grant will include a specific scope.

Example:

  • An app requests the idp:character:?.read scope to get access to data for one of the user's characters of their choice.
  • The user is shown a consent screen and chooses Vielle Janlenoux (Omega).
  • The returned access token has the idp:character:37681922.read scope instead.

The consent screen allows the user to grant only some requested scopes. App permissions are stored server-side, and the user is free to revoke any of them at any point, so an access token with the right scopes is not by itself a guarantee that the request will succeed, as the app's access to the scope may have been revoked by the user since the token was issued.

The actual permissions granted to an access token at API request time are an intersection of:

  • the scopes assigned to the token itself
  • the user's ACL for the app
  • the user's own permissions (i.e. a token cannot be used to access resources the user can't access)

Token expiration

Access tokens expire after two hours, though for typical use cases they'll be single-use.

Refresh tokens expire after 180 days if unused. Most apps using the Identity API won't need them, though they may see use for the Roleplay API. All refresh tokens are single-use; using a refresh token to issue a new access token invalidates that refresh token, and the authorization server will return a new one in the /token response. The client must use the new refresh token for the next request.

The app developer can immediately revoke all access and refresh tokens issued to the app by pressing the "Revoke all user tokens" button at the bottom of the "Edit App" page.