Integration Guide

How to integrate your application with the Holibob authentication service.

1. Redirecting to the Auth Site

When a user needs to sign in, redirect them to the Auth service with the following query parameters:

Parameter	Type	Description
returnUrl	string	URL to redirect to after authentication
origin	string	Identifier for the calling application

Example redirect

window.location.href = `https://auth.holibob.tech/signin?returnUrl=${encodeURIComponent(window.location.href)}&origin=hub`;

2. Handling the Callback

After successful authentication, Auth redirects back to your returnUrl with a token query parameter containing the JWT access token.

Extract token from callback

const url = new URL(window.location.href);
const token = url.searchParams.get("token");
if (token) {
    // Store the token (e.g., in memory or sessionStorage)
    sessionStorage.setItem("accessToken", token);
    // Clean the URL
    url.searchParams.delete("token");
    window.history.replaceState({}, "", url.toString());
}

3. Using the Token

Include the access token in the Authorization header for all API requests:

API request with token

fetch("https://api.holibob.tech/graphql", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({ query: "{ me { id email } }" }),
});

4. Refreshing the Token

Access tokens expire after 15 minutes. To get a new token without requiring the user to sign in again, call the refresh endpoint. The refresh token is stored in an HttpOnly cookie and sent automatically.

Refresh token request

const response = await fetch("https://auth.holibob.tech/api/refresh", {
    method: "POST",
    credentials: "include", // Required to send the refresh cookie
});
const { token } = await response.json();

5. Sign Out

To sign a user out, redirect them to the Auth signout page:

window.location.href = "https://auth.holibob.tech/signout";

This clears the refresh token cookie and invalidates the session.

6. Error Handling

If authentication fails, Auth redirects back with an error query parameter:

const error = url.searchParams.get("error");
if (error) {
    // Handle the error — e.g., display a message or redirect to a login page
    console.error("Authentication failed:", error);
}

Error codes follow the pattern E1xxx for sign-in, E2xxx for sign-up, E3xxx for refresh, E4xxx for MFA, and E5xxx for passkeys.