Getting Started

Central Archives provides two APIs:

• The Identity API is the API that lets Central Archives act as an identity provider or a single sign-on provider.
• The Roleplay API allows retrieving and editing characters' roleplay profiles. If you're using Central Archives only as an identity provider rather than a roleplay portal, you can ignore it.

Both APIs involve external apps — be they websites, mobile apps, or Dalamud plugins — acting on behalf of the Central Archives user. For an app to be able to access Central Archives functionality programmatically, the user must first authorize it to do so (via a "Do you allow this app to do that?" consent page). After obtaining authorization from the user, the app then calls the actual API it's interested in, passing it an access token — a special string representing the user's authorization to let the app access this specific functionality.

Apps obtain access tokens from the Central Archives authorization server, which follows the OAuth 2.0 standard. The authorization server must know what the app is called and what it can and cannot do. Therefore, as an app developer seeking to integrate with Central Archives, you first have to register your app via the developer section of the Central Archives website.

Creating your developer account

If you're already a Central Archives user (this includes Chaos Archives and Crystal Archives), and you have verified your email address and character, you can register your app right away — there's no need to request any special developer privileges.

If you don't have a Central Archives account, create it. You will be asked for your email address, password, and one character to verify. You can always add more characters to your account later.

After you've verified your account, the "For developers" section will become available on the sidebar. On the "My apps" page, you will be able to view all apps you have registered.

Registering your app

To register your app, follow the app registration guide. You will be asked for the app name, type, and permissions it can request.

Obtaining access tokens

As your app will be used by Central Archives users, it will need to obtain access tokens to commuicate with the Central Archives APIs on the user's behalf. This is something the app will need to do in its own code by interacting with the Central Archives authorization server as an OAuth 2.0 client. You can either implement this yourself or, preferably, use an existing OAuth 2.0 client library for your programming language or platform.

For details on interfacing with the authorization server, see:

• Authorizing a website or mobile app
• Authorizing a Dalamud plugin

Calling the APIs

Once you obtain an access token, you pass it to the API endpoint of interest in the Authorization HTTP header, like this: Authorization: Bearer <access token>.

For example, suppose the authorization server has issued your app an access token, ABCDEF123456, that lets it access one or more of the user's characters, and you want to call the character list API to obtain information about characters you have access to. To do this, you issue an HTTP GET request to the API endpoint

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

and pass it this HTTP header:

Authorization: Bearer ABCDEF123456

Your HTTP client library might have a more convenient way to pass authorization headers than building the string manally.