This document holds sample authentication flows for various use cases for XIVAuth.

User-Based Authentication

In user-based authentication, the Relying Party wishes to authenticate against a particular user, rather than a character. This authentication model is beneficial when a service wishes to track a particular player rather than a character (e.g. for moderation or community purposes). Examples of applications that would use user-based authentication are forums, game mod platforms, license management systems, or general user-level activity.

1. On the Relying Party’s site, a user selects the Sign In with XIVAuth button.
2. The Relying Party generates a redirect to XIVAuth and requests the user scope. The user is served the redirect and is taken to XIVAuth.
3. The user (if necessary) signs in to XIVAuth and is taken to a consent screen where they may review the requested scopes and make changes if necessary.
4. Upon consent authorization, XIVAuth will generate an authorization_code and redirect the user back to the Relying Party’s site, in standard OAuth fashion.
5. The Relying Party redeems the authorization_code for an access_token which can be used in future requests.
6. The Relying Party issues an API call to /users in order to retrieve user information.
   1. Depending on the approved scopes, certain fields such as email address may or may not be present.

If the Relying Party has requested additional scopes, they will be able to make any required API calls using their access_token until such time as it expires. This may be used if a Relying Party wishes to request both user and character information.

Character-Based Authentication

For services that do not require user management or do not care about the underlying user, Character-Based Authentication may be used instead. In this mode, XIVAuth will only allow an Access Token to retrieve one (or more) characters depending on the user’s consent choices. Examples of applications that would use character-based authentication are character leaderboards, marketplace applications, or other services that do not wish to track or work with users.

1. On the Relying Party’s site, a user selects the Sign In with XIVAuth button.
2. The Relying Party generates a redirect to XIVAuth and requests the character scope. The user is served the redirect and taken to XIVAuth.
   1. Depending on the application’s configuration and needs, the character:all scope may be requested instead.
3. The user (if necessary) signs in to XIVAuth and is taken to a consent screen where they may review the requested scopes and make changes if necessary. During this consent screen, the user will also select the character they would like to log in to the Relying Party with.
   1. If the character:all scope was selected, the user will be able to select one or more characters.
   2. If the user does not have any verified characters on their account, they will be shown an error and the OAuth flow will be aborted. The Relying Party will not receive notification of this event.
4. Upon consent authorization, XIVAuth will generate an authorization_code and redirect the user back to the Relying Party’s site, in standard OAuth fashion.
   1. Internally, XIVAuth will also create an ACL record listing what character(s) the authorization_code is permitted to use.
5. The Relying Party redeems the authorization_code for an access_token which can be used in future requests.
   1. Internally, the ACL listing is copied from the authorization_code over to the access_token.
6. The Relying Party issues an API call to /characters in order to retrieve character information.
   1. If the character scope was passed, there will always be one (and only one) entry in the returned API call. However, if the character:all scope was requested, there may be one or more entries in the returned call. In the latter case, it is the responsibility of the Relying Party to handle character selection.

Developers wishing to use character authentication should rely on the persistent_key field rather than lodestone_id. The persistent_key field is derived from the user’s ID and Lodestone ID, and is guaranteed to not change if the user deletes and recreates the character, but will change if the character is moved to a different user’s account. Developers should take care of gracefully handling this case to prevent data leakage between users if a character is transferred.

If additional scopes were requested, the Relying Party may use the Access Token for those queries as well. Unless the user scope was requested in addition to the character scope, the Relying Party will not be able to request user information.