@multiauthy/sdk

Official SDK for MultiAuthy — unified OAuth infrastructure. Configure every provider once, receive a normalized user profile every time.

Installation

npm install @multiauthy/sdk
# or
bun add @multiauthy/sdk
# or
yarn add @multiauthy/sdk

Quick start

import { MultiAuthy } from "@multiauthy/sdk"

const auth = new MultiAuthy({
  apiKey:    process.env.MULTIAUTHY_KEY!,
  projectId: process.env.MULTIAUTHY_PROJECT!,
})

// Express
app.get("/login/:provider", (req, res) => {
  res.redirect(auth.login(req.params.provider))
})

app.get("/callback/:provider", auth.callback(), (req, res) => {
  console.log(req.user) // NormalizedUser
  res.redirect("/dashboard")
})

API

new MultiAuthy(config)

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | ✓ | Your project-scoped API key (ma_live_…) | | projectId | string | ✓ | Your project UUID | | baseUrl | string | — | Override the MultiAuthy instance URL | | timeout | number | — | Request timeout in ms (default: 10000) |

auth.login(provider, options?)

Returns the authorization URL for the given provider. Redirect the user to it.

app.get("/login", (req, res) => {
  res.redirect(auth.login("google", { redirectUri: "https://myapp.com/callback" }))
})

auth.callback(provider?)

Express middleware. Validates the OAuth exchange, attaches req.user, calls next().

app.get("/callback/:provider", auth.callback(), (req, res) => {
  res.json(req.user)
})

auth.exchange(code, state, provider)

Low-level exchange. Returns a NormalizedUser or throws a MultiAuthyError.

auth.callbackResult(code, state, provider)

Same as exchange() but returns { ok, user?, error?, code? } instead of throwing.

auth.providers()

Lists providers configured for this project.

auth.ping()

Health check — verifies your API key and project ID.

Normalized user object

Every provider returns the same shape:

interface NormalizedUser {
  id:       string   // provider-scoped UID
  provider: string   // "google" | "github" | …
  email:    string
  name:     string
  username: string   // handle (empty if provider doesn't expose one)
  avatar:   string   // URL
  verified: boolean  // email verified?
  raw?:     object   // raw provider response
}

Error handling

All errors extend MultiAuthyError and expose .code and .statusCode:

import { MultiAuthy, AuthenticationError, ProviderNotConfiguredError } from "@multiauthy/sdk"

try {
  const user = await auth.exchange(code, state, "google")
} catch (err) {
  if (err instanceof AuthenticationError) { /* bad API key */ }
  if (err instanceof ProviderNotConfiguredError) { /* provider not set up */ }
}

CLI

After installing the SDK you get a multiauthy binary:

# First-time setup
multiauthy login

# Create a project
multiauthy projects create

# Add Google OAuth provider
multiauthy providers add --project <id>

# Create an API key
multiauthy keys create --project <id> --name production

Run multiauthy --help for the full command reference.

License

MIT — see LICENSE.