Authly SDK

Authly SDK is a production-ready, headless authentication client designed to work with an Authly-compatible authentication server.

It provides secure authentication, automatic token refresh, session management, and multi-device login support — without enforcing UI, framework, or vendor lock-in.

Authly is ideal for web apps, dashboards, internal tools, and APIs that need robust authentication without reinventing auth infrastructure.

📚 Full Documentation

---

Features

• ✅ Email & password authentication
• 🔄 Automatic access token refresh
• 🔐 Refresh token rotation
• 📱 Multi-device session management
• 🚪 Session revocation (per device)
• 🔓 Logout and logout-all support
• 📘 Strongly typed SDK (TypeScript-first)
• 🌐 Works in browser and Node.js

---

Installation

npm install authly-sdk

---

Backend Requirement (Important)

Authly is a headless authentication system.

This SDK does not include a backend.
You must run an Authly-compatible authentication server for the SDK to work.

You have:

Option (V1): Use the Official Authly Server (Recommended)

Clone and run the official Authly server:

https://github.com/Prateet-Github/authly-server

This server provides:

• User management
• Password hashing
• JWT + refresh tokens
• Session tracking
• Email verification & password reset primitives

(For full setup check out our official documentation site)

Once running, configure the SDK with your server URL:

const authly = new AuthlyClient({
  baseUrl: "https://your-auth-server.com/api",
});

---

## Quick Start

```typescript
import { AuthlyClient } from "authly-sdk";

const authly = new AuthlyClient({
  baseUrl: "http://localhost:5001/api",
});

Register

await authly.register({
  email: "user@example.com",
  password: "password123",
  name: "John Doe",
});

Login

const user = await authly.login({
  email: "user@example.com",
  password: "password123",
});

console.log(user);

Get Current User

const me = await authly.me();
console.log(me);

---

Automatic Token Refresh

Authly automatically refreshes expired access tokens using the refresh token.

No manual refresh handling is required.

If the refresh token expires, a SESSION_EXPIRED error is thrown and the user must re-authenticate.

---

Session Management

List Active Sessions

const sessions = await authly.getSessions();
console.log(sessions);

Each session includes:

• Device type
• Browser
• Operating system
• IP address
• Last activity
• Whether it is the current session

Revoke a Session (Device Logout)

await authly.revokeSession(sessionId);

Logs the user out from that specific device.

Logout (Current Session)

await authly.logout();

Logs out from the current session.

Logout from All Devices

await authly.logoutAll();

Revokes all active sessions and logs the user out everywhere.

---

Authentication State

if (authly.isAuthenticated()) {
  console.log("User is logged in");
}

---

Error Handling

Authly throws structured errors using AuthlyError.

import { AuthlyError } from "authly-sdk";

try {
  await authly.me();
} catch (err) {
  if (err instanceof AuthlyError) {
    console.log(err.code);
    console.log(err.message);
  }
}

Error Codes

Code	Description
INVALID_CREDENTIALS	Email or password is incorrect
EMAIL_NOT_VERIFIED	Email verification required
SESSION_EXPIRED	Refresh token expired, re-authentication needed
UNAUTHORIZED	Authentication required
FORBIDDEN	Insufficient permissions
NOT_FOUND	Resource not found
RATE_LIMITED	Too many requests
UNKNOWN_ERROR	Unexpected error occurred

---

Storage Options

Default (In-Memory)

Used automatically in Node.js and server environments.

Browser Storage

import { BrowserStorage } from "authly-sdk";

const authly = new AuthlyClient({
  baseUrl: "http://localhost:5001/api",
  storage: new BrowserStorage(),
});

Uses localStorage for token persistence.

---

Requirements

• Authly authentication server running
• Node.js 18+ or modern browser
• Fetch API support

---

Versioning

This SDK follows semantic versioning.

• v0.x — early development
• v1.0 — stable public API

---

License

MIT License

---

Disclaimer

Authly SDK is a client library.

Security guarantees depend on correct usage of the Authly server, HTTPS, and secure deployment practices.

📚 Full Documentation