Authentication

WARNING

Before continuing, you must have a working OAuth2 link.
You can generate one using the OAuth2 Link Builder.
Do not continue without one.

---

Overview

The authentication endpoint allows you to verify a user’s access token and retrieve their profile data, scopes, and linked providers.

Endpoint:
GET https://auth.hawaiian.gg/api/auth/@users/verify

This endpoint validates the token provided by the user and returns a structured payload with identity information.

---

Request

Headers

Key	Value	Required
Authorization	Bearer <ACCESS_TOKEN>	✅
Content-Type	application/json	✅

Example Request (Node.js)

import fetch from 'node-fetch';
const params = new URLSearchParams(window.location.search);
const token = params.get("token");

if (!token) {
	error = "No token found in URL";
	loading = false;
	return;
}

// Call API to verify token
const res = await fetch(`/api/auth/@users/verify?`, {
	method: "GET",
	headers: {
		"Authorization": `Bearer ${token}`,
		"Content-Type": "application/json",
		"Accept": "application/json"
    }
});


if (!res.ok) {
    error = `Verification failed: ${await res.text()}`;
    loading = false;
    return;
}

payload = await res.json();
console.log(payload);

TIP

Replace token with the token obtained from your OAuth2 authorization flow.

Example Response

{
  "iss": "hawaiian.gg",
  "aud": "auth.hawaiian.gg",
  "iat": 1755146977,
  "exp": 1755147577,
  "jti": "1712dd82-1d7f-4d2d-97f2-0e718da06e04",
  "scopes": [
    "identify",
    "email",
    "profile",
    "google",
    "roblox",
    "discord"
  ],
  "providers": {
    "discord": {
      "id": "896507572234895420",
      "username": "verifiedhawaii",
      "avatar": "bd7901ebeecfbe0d07b94e882b5cda86"
    },
    "google": {
      "id": "109350302777377037234",
      "email": "verifiedhawaii44@gmail.com",
      "name": "verified hawaii",
      "picture": "https://lh3.googleusercontent.com/a/ACg8ocICYCC7ManL_kMU9CKjdH9xOh4UBCB42gIAtFVy8D8Y0g8G1o8=s96-c"
    },
    "roblox": {
      "id": "512756278",
      "username": "VerifiedHawaii"
    }
  },
  "metadata": {
    "createdAt": "2025-08-14T04:49:37.709Z",
    "authorizer": "hawaiian.gg"
  },
  "sub": null
}

Response Fields

Field	Description	Required
iss	Token issuer (hawaiian.gg)	✅
aud	Audience for the token	✅
iat	Issued at (Unix timestamp)	✅
exp	Expiration time (Unix timestamp)	✅
jti	Unique token identifier	✅
scopes	Permissions granted to the application	✅
providers	Linked account information from OAuth2 providers	✅
metadata	Creation date and authorizer	✅
sub	Subject — may be null if not applicable	❌

Common Errors

Status Code	Meaning
401	Unauthorized – Missing or invalid token
403	Forbidden – Token does not have required scopes
500	Internal Server Error – An error occurred on the server