Programmatically manage FaableAuth users, teams, connections and clients through the FaableAuth REST API.

⚠️ Server-side only. This SDK uses administrative credentials. Never ship it to a browser or any untrusted runtime.

Install

npm install @faable/auth-sdk

Authentication

The SDK accepts any auth strategy from @faable/sdk-base. Two strategies are typically used:

Client credentials (recommended)

Reads FAABLE_CLIENT_ID, FAABLE_CLIENT_SECRET and FAABLE_DOMAIN from the environment by default:

import { FaableAuthApi } from "@faable/auth-sdk";
import { createClientCredentials } from "@faable/sdk-base";

const api = FaableAuthApi.create({
  auth: createClientCredentials(),
  team_id: "team_xxxxxxxxxxxxxxxxxxxxxxxx",
});

You may also pass credentials explicitly:

const auth = createClientCredentials({
  client_id: process.env.FAABLE_CLIENT_ID!,
  client_secret: process.env.FAABLE_CLIENT_SECRET!,
  domain: "faable.auth.faable.link",
});

API key

import { FaableAuthApi } from "@faable/auth-sdk";
import { createApikeyAuth } from "@faable/sdk-base";

const api = FaableAuthApi.create({
  auth: createApikeyAuth("fak_xxxxxxxxxxxxxxxx"),
  team_id: "team_xxxxxxxxxxxxxxxxxxxxxxxx",
});

Constructor options

| Option | Type | Description | | ------------ | -------- | -------------------------------------------------------------------------------------------- | | auth | strategy | Auth strategy from @faable/sdk-base. Required. | | team_id | string | Scopes calls to a specific team (sent as x-faable-team header). | | account_id | string | Scopes calls to a specific FaableAuth account (sent as x-faableauth-account header). | | domain | string | Override the API host. Defaults to https://faable.auth.faable.link. | | debug | boolean | Enables verbose logging in the underlying fetcher. |

Usage

Users

// Get a user
const user = await api.getUser("user_xxx");

// Create a user
const created = await api.createUser({
  email: "[email protected]",
  password: "•••••••••",
});

// Update a user
const updated = await api.updateUser("user_xxx", { phone: "+34XXXXXXXXX" });

// List users (paginated) — first page of 30
const firstPage = await api.listUsers().first();

// Filter by email
const matches = await api.listUsers({ email: "[email protected]" }).first();

// Iterate every page
for await (const page of api.listUsers()) {
  for (const user of page) {
    // ...
  }
}

User metadata

const metadata = await api.getUserMetadata("user_xxx");

await api.setUserMetadata("user_xxx", {
  onboarded: true,
  plan: "pro",
});

Teams

const team = await api.getTeam("team_xxx");

const newTeam = await api.createTeam({ name: "Acme Inc." });

await api.deleteTeam("team_xxx");

const myTeams = await api.listTeams({ user_id: "user_xxx" }).first();

Team members

const members = await api.listTeamMembers({ query: "alice" }).first();

const isMember = await api.isUserMemberOfTeam("user_xxx", "team_xxx");

Connections

const connections = await api.listConections().first();
const connection = await api.getConection("conn_xxx");

Clients

const clients = await api.listClients().first();
const client = await api.getClient("client_xxx");

Current account

const account = await api.currentAccount();

Pagination

List methods return a paginator. Use .first() to grab the first page or iterate with for await ... of to walk all pages:

const paginator = api.listUsers();

const firstPage = await paginator.first();

for await (const page of paginator) {
  // each `page` is an array of items
}

Types

All response shapes are generated from the OpenAPI spec and re-exported from the package root:

import type { User, Team, TeamMember, Connection, Client } from "@faable/auth-sdk";

License

MIT