Skip to content

Registering Your App

To register your app with the Central Archives authorization server, select the "register an app" link on the sidebar on centralarchives.org.

Register OAuth App

Here you get to make some choices:

  • Your app name can be anything, but it must be unique.
  • Your app icon and description will be displayed to the user on the consent screen. You can upload your own icon, which must be square (have the same width and height).

The most important choice to make here is the type of the app.

  • For a server-side app, the code responsible for obtaining the access token executes on a server. This means that the app can store secrets that a user can't read. Choose this option if you have a web app with a backend under your control.
  • For a web app, the code responsible for obtaining the access token executes in the user's browser. Choose this option if you have a pure-frontend web app without a backend.
  • For a native app, the code responsible for obtaining the access token executes as part of a desktop or mobile application. Dalamud plugins, since they execute as part of the FFXIV game process, also fall under this category.

Enabled authorization flows

An authorization flow is the sequence of steps by which an app obtains an API access token.

Server-side and web apps can only use the authorization code flow. It's also recommended for mobile apps. Native apps, as an alternative, can enable the device flow or both.

To use the authorization code flow, the app needs to control a URL. As part of the authorization process, Central Archives will redirect to that URL with a special query parameter that can be exchanged for an access token. Normally, this URL will use the HTTPS scheme (something like https://myapp.com/redirect). Mobile apps for Android and iOS can register a custom URL scheme, which will result in the system opening the app and passing it the desired parameters when the user's browser navigates to that URL.

This leaves Dalamud plugins. To listen to a URL, they would have to spin up a local web server and then listen to redirects on http://localhost:some_port, which is inherently prone to impersonation. They will be better off using the device flow, in which they open a consent page URL provided by the authorization server and then periodically poll for the access token, which is obtained when the user approves the request in their browser.

To summarize:

  • Use the device flow for Dalamud plugins and other desktop apps that can't register a URL.
  • Use the authorization code flow for everything else.

Requestable scopes

This is a list of checkboxes that defines the list of permissions (scopes in OAuth terminology) that the app can request. Select only those that are needed for the app to function. The authorization server will reject requests that try to request a scope the app didn't opt for.

For more information, see Scopes and Permissions.

Redirect URIs

Apps using the authorization code flow must register at least one URI where the authorization server can redirect the browser after completing the authorization request. This can be any URI the app controls, with the only restriction being that insecure HTTP (http://) is only allowed for localhost (and IP addresses that resolve to localhost), while all other hosts must use HTTPS (https://) or a custom scheme.

The authorization server will refuse requests that ask to be redirected to any URI outside of this list provided by the app developer. This is necessary so that a malicious app can't impersonate a legitimate app using its client ID, but redirect the user to https://evil-hax.com and steal an access token meant for the legitimate app.

Apps using only the device flow don't need to register any redirect URIs.

Client ID and client secret

When you create your app, it will be assigned a client ID, which is a UUID (example: 7d49c185-2fcf-4cc6-9f79-fcfa120e358f). You will pass this value to the authorization server so it can uniquely identify your app.

Server-side apps, in addition, will be issued a randomly generated client secret.

Client secret

Treat the client secret like a password. It will only shown to you once, so make sure to copy it and save it in a secure location. Do not commit it to version control, as Central Archives will use it as additional proof that authorization requests are coming from your app server.

If you lose your client secret, you can regenerate it at any time from the Edit OAuth App page.