Eternal-Twin uses the OAuth 2.0 authorization framework to expose its data to the game websites. Each game website is an OAuth 2 client.

Client creation

The first step is to create an OAuth client. It is not exposed publicly yet.

The creation options are:

  • General information: display name, homepage URI
  • Technical: OAuth redirect (callback) URI

The server creates the application and picks a random secret. The secret is returned as clear-text in the creation response, it is never returned again. The server treats the secret as a password and only stores its hash.

Authorization request

To authenticate a user, the client must redirect the end user to Eternal-Twin to request its authorization.

The base URI is, with the following query parameters:

client_idRequired. Client ID received during the client creation
redirect_uriRedirection URI. The default and only accepted value is the one configured during the app creation
loginNot yet implement: username to use by default
scopeNot yet implement: scopes to request
stateA string returned as-is
methodAuthentication method suggestion if the user needs to sign-in (etwin, twinoid, hammerfest). Default: etwin



The state parameter is a string returned as-is once the user has authenticated. It must include an unguessable part to prevent CSRF attacks.

For the system clients, we use a JWT based on this RFC draft for the state. In particular, it has a "Request Forgery Protection" (rfp) field.

Redirect URI

Eternal-Twin does not allow dynamic redirect URIs. Use the state parameter to encode state.

For the system clients, we use https://<game>/oauth/callback if the client supports only one authorization server (Eternal-Twin), or https://<game>/oauth/callback/<as> where as is a string identifying the authorization server.