Skip to content

Character API

Use this API if your app wants to do character-based authentication (i.e. sign in your user as a particular character).

Retrieving a character by Lodestone ID

To retrieve a character by Lodestone ID, the app must possess an access token with the idp:character:<lodestoneId>.read or idp:character:all.read scope, which is passed in the Authorization: Bearer header.

Make a GET request to the endpoint:

https://centralarchives.org/api/idp/v1/characters/<lodestone ID>

Possible response status codes are:

  • 200 OK: The request is successful, and character data is returned.
  • 401 Unauthorized: No access token, or a malformed or expired access token, was supplied.
  • 403 Forbidden: This access token does not have the required scope to access this character, or the user has revoked app consent.
  • 404 Not Found: This character is not registered on Central Archives, does not belong to this user, or is not verified.

The success response body is a JSON object of the form:

{
  "persistentKey": "IdyMga_n-FQe_9Rp_B2zQX3auhQ",
  "lodestoneId": "12345678",
  "name": "John Finalfantasy",
  "world": "Midgardsormr",
  "datacenter": "Aether",
  "region": "na",
  "avatarUrl": "https://img2.finalfantasyxiv.com/f/...",
  "portraitUrl": "https://img2.finalfantasyxiv.com/f/...",
  "createdAt": "2023-06-18T06:21:39.574Z",
  "verifiedAt": "2023-06-18T06:26:09.287Z",
  "updatedAt": "2023-06-18T06:26:09.293Z"
}

Most of these fields are self-explanatory. Here are things of note:

  • persistentKey: This field is used to uniquely identify a character bound to a certain user. It is calculated as HMAC(userId + lodestoneId, backendSecret) and is guaranteed to remain consistent for any specific user. When using character-only authentication flows (rather than just verification), it is recommended to identify through persistentKey to avoid leaking account information in the event that a character is moved to a different Central Archives user.
  • region: This is an enum field whose possible values are eu, na, jp and oc.
  • createdAt, verifiedAt, updatedAt: These are date/time fields in the ISO 8601 format.

Retrieving all accessible characters

To retrieve the list of the user's characters, the app must possess an access token with the idp:character:<lodestoneId>.read or idp:character:all.read scope, which is passed in the Authorization: Bearer header.

Note

One access token can be granted multiple idp:character:<lodestoneId>.read scopes for different characters of the same user.

To retrieve all of the user's characters accessible via the app's access token, make a GET request to the endpoint:

https://centralarchives.org/api/idp/v1/characters

Possible response status codes are:

  • 200 OK: The request is successful, and character data is returned.
  • 401 Unauthorized: No access token, or a malformed or expired access token, was supplied.
  • 403 Forbidden: This access token does not have the required scope to access this character, or the user has revoked app consent.

The success response body is a JSON array, possibly empty if the user has revoked access to all retrievable characters:

[
  {
    "persistentKey": "IdyMga_n-FQe_9Rp_B2zQX3auhQ",
    "lodestoneId": "12345678",
    "name": "John Finalfantasy",
    "world": "Midgardsormr",
    "datacenter": "Aether",
    "region": "na",
    "avatarUrl": "https://img2.finalfantasyxiv.com/f/...",
    "portraitUrl": "https://img2.finalfantasyxiv.com/f/...",
    "createdAt": "2023-06-18T06:21:39.574Z",
    "verifiedAt": "2023-06-18T06:26:09.287Z",
    "updatedAt": "2023-06-18T06:26:09.293Z"
  },
  {
    "persistentKey": "Qhua3XQz2B_pR9_eQF-n_agMydI",
    "lodestoneId": "87654321",
    "name": "Jane Finalfantasy",
    "world": "Ragnarok",
    "datacenter": "Chaos",
    "region": "eu",
    "avatarUrl": "https://img2.finalfantasyxiv.com/f/...",
    "portraitUrl": "https://img2.finalfantasyxiv.com/f/...",
    "createdAt": "2024-02-18T06:21:39.574Z",
    "verifiedAt": "2024-02-18T06:26:09.287Z",
    "updatedAt": "2024-02-18T06:26:09.293Z"
  }
]

For notes on the fields, see above.