Add Sign in with Maiaddy

This guide walks through adding Sign in with Maiaddy to a web app using the Maiaddy ID JavaScript SDK. By the end you'll have a real OAuth 2.0 + OIDC flow, a user session, and the access token you need to call any Maiaddy API.

1. Install the SDK

Install the JavaScript SDK from npm. It works with any modern bundler — Vite, Next.js, Remix, plain webpack — and ships ESM and CommonJS builds.

npm install @maiaddy/id-js

2. Initialize the SDK

In your app entry, initialize the SDK with the client_id and redirect_uri you registered. The SDK takes care of state generation, PKCE, and the OAuth 2.0 dance.

import { MaiaddyID } from "@maiaddy/id-js";

const maiaddy = new MaiaddyID({
  client_id: "your_client_id",
  redirect_uri: "https://your-app.com/auth/callback",
  scope: "openid profile email",
});

The scope value follows OIDC conventions. If your app needs additional Maiaddy permissions (for example developers:manage for the developer console), add them space-separated.

3. Wire the sign-in button

Attach the SDK to your sign-in trigger. Calling signIn() redirects the browser to the Maiaddy ID authorize endpoint.

<button id="signin">Sign in with Maiaddy</button>

<script>
  document.getElementById("signin").addEventListener("click", () => {
    maiaddy.signIn();
  });
</script>

4. Handle the callback

After the user authenticates, Maiaddy ID redirects back to your registered redirect_uri with code and state in the URL. Call handleCallback() on that route to exchange the code for tokens.

import { MaiaddyID } from "@maiaddy/id-js";

const maiaddy = new MaiaddyID({
  client_id: "your_client_id",
  redirect_uri: "https://your-app.com/auth/callback",
});

const session = await maiaddy.handleCallback(window.location.href);
console.log(session.user);          // { id, email, displayName, ... }
console.log(session.accessToken);   // bearer token for API calls

5. Call a Maiaddy API

Use session.accessToken as a Bearer token on any authenticated Maiaddy API request.

const response = await fetch("https://api.maiaddy.com/baseapi/v1/me", {
  headers: {
    Authorization: `Bearer ${session.accessToken}`,
    Accept: "application/json",
  },
});
const me = await response.json();

6. Refresh and sign out

The SDK exposes refresh() to swap an expiring access token for a fresh one using the refresh token, and signOut() to clear the local session and redirect to the Maiaddy ID end-session endpoint.

// Background token refresh
const fresh = await maiaddy.refresh();

// Sign out
maiaddy.signOut();

What's next

• Read the Maiaddy ID reference for endpoint details and request/response schemas.
• Issue an API key from the console and try a request against any of the catalog APIs.
• Browse the other guides for product-specific walkthroughs.