Authentication

The Authentication API provides secure methods for authenticating users with the Gamerbase API. It supports multiple authenticate protocols including OAuth 2.0, ZKLogin, SIWE and Password.

Session Management

Session tokens have a TTL of 10 minutes. When a session token has expired the refresh-session endpoint must be called with the refresh token to generate a new session token. Refresh tokens have a TTL of 30 days.

Refresh Session

POST /v1/user/auth/refresh-session

The Refresh Session API allows you to obtain a new session token from a refresh token.

Request Body

Name	Type	Description
refreshToken*	String	Required

201: Created

{
  "sessionToken": "string"
}

OAuth

The following authentication methods leverage trusted OAuth providers. The credential or token property are required depending on the auth method for Google Login the required field is a credential string. For all other OAuth authentication methods the token property is required. The token property is an encrypted JWT containing user OAuth data and a _nonce property. The JWT must be encrypted using a shared secret that is configured in the tenant of the consuming community.

Example

const decodeSharedSecret = (secret: string): Uint8Array => {
  if (!secret || secret.length % 2 !== 0) return Uint8Array.of();
  const buffer = new Uint8Array(secret.length / 2);
  for (let n = 0; n < secret.length / 2; n++) {
    const chunk = secret.substring(n * 2, n * 2 + 2);
    buffer[n] = Number.parseInt(chunk, 16);
  }

  return buffer;
};

const nonce = randomBytes(8).toString("hex")
const key = decodeSharedSecret(process.env.SHARED_SECRET);

const rawToken = new EncryptJWT({
  _nonce: nonce,
  subjectId,
  handle,
  idToken,
  accessToken,
  refreshToken,
  referrerHandle,
})
  .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
  .setIssuedAt(now)
  .setExpirationTime(now + 300);

const token = await rawToken.encrypt(key);

JWT Payload

interface JWT {
  _nonce: string, // Length 8
  subjectId: string,
  handle: string,
  idToken: string, // Only required for ZKLogin
  accessToken: string,
  refreshToken: string,
  referrerHandle: string, // Consumed as a query param
}

Google

POST /v1/user/auth/google/login

The Google Login API allows users to sign in using their Google account.

Request Body

Name	Type	Description
credential	String	Required
referrerHandle	String	Optional

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}

Discord

POST /v1/user/auth/discord/login

The Discord Login API allows users to sign in using Discord credentials.

Request Body

Name	Type	Description
token	String	Required
accessToken	String	Optional
referrerHandle	String	Optional

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}

Twitter

POST /v1/user/auth/twitter/login

The Twitter Login API allows users to sign in using Twitter credentials.

Request Body

Name	Type	Description
token*	String	Required
accessToken*	String	Optional
referrerHandle*	String	Optional

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}

ZKLogin (OAuth)

Logging in with any ZKLogin endpoint automatically creates a SUI wallet for that user. The wallet is linked to the OAuth provider they logged in with. When utilising ZKLogin as the primary authentication mechanism it is required to enforce "primary account login". This ensure that a user always logs in with the account they used to register, this maintains consistency in the wallet address that is created for the user.

For more information on the implementation of ZKLogin please reference the SUI Docs.

Google

POST /v1/user/auth/google/zklogin

The Google ZKLogin API allows users to perform ZKLogin using Google credentials.

Request Body

Name	Type	Description
token*	String	Required
accessToken*	String	Optional
referrerHandle*	String	Optional

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}

Twitch

POST /v1/user/auth/twitch/zklogin

The Twitch ZKLogin API allows users to perform ZKLogin using Twitch credentials.

Request Body

Name	Type	Description
token*	String	Required
accessToken*	String	Optional
referrerHandle*	String	Optional

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}

SIWE

POST /v1/user/auth/siwe/login

The SIWE Login API allows users to sign in using SIWE credentials (Sign In WIth Ethereum)

Request Body

Name	Type	Description
message*	String	Required
signature*	String	Required
referrerHandle*	String	Optional

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}

Password

Register

POST /v1/user/register/password

The Password Register API allows users to signup using their password credentials.

Request Body

Name	Type	Description
username	String	Required
password	String	Required

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}

Login

POST /v1/user/auth/password/login

The Password Login API allows users to sign in using their password credentials.

Request Body

Name	Type	Description
username	String	Required
password	String	Required

201: Created

{
  "userId": "string",
  "sessionToken": "string",
  "refreshToken": "string"
}