Skip to content

User API

Use this API if your app wants to do user-based authentication (i.e. sign in your user with their Central Archives account, irrespective of characters).

Why a custom API? Why not OpenID Connect?

OpenID Connect is a complicated spec on top of another, already complicated spec (OAuth 2.0). It would be mostly useless since Central Archives doesn't store any personal information about its users other than their email addresses, by design — and it's recommended that apps don't ask even for that, instead relying only on the user ID to map their own user accounts to Central Archives user accounts.

If it's any consolation, Discord doesn't support OpenID Connect either, yet it doesn't stop external services from using it as an identity provider.

Retrieving user information

To retrieve user information, the app must possess an access token with the user.read scope, which is passed in the Authorization: Bearer header.

Make a GET request to the endpoint:

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

Possible response status codes are:

  • 200 OK: The request is successful, and user 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 user information, or the user has revoked app consent.

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

{
  "id": "5a0a2bdf-83ed-49f5-8671-8fa4834c3bf2",
  "emailVerified": true,
  "mfaEnabled": true,
  "verifiedCharacters": true
}

If the access token additionally has the idp:user:email.read scope, the response will include an additional field, email:

{
  "id": "5a0a2bdf-83ed-49f5-8671-8fa4834c3bf2",
  "email": "user@example.com",
  "emailVerified": true,
  "mfaEnabled": true,
  "verifiedCharacters": true
}

The meaning of the fields is:

  • id: UUID that uniquely identifies this Central Archives user account. It will never change.
  • email: User email address.
  • emailVerified: Whether the user has verified their email address.
  • mfaEnabled: Whether the user has multi-factor authentication enabled.
  • verifiedCharacters: Whether the user has any verified characters.