> For the complete documentation index, see [llms.txt](https://impoo.gitbook.io/authenticationsystem/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://impoo.gitbook.io/authenticationsystem/developers/api-reference.md).

# API Reference

This page provides an overview of the AuthSystem API. The API consists of four main components:

* [`AuthSystemApi`](/authenticationsystem/developers/authsystemapi.md) — the main entry point
* [`AuthManager`](/authenticationsystem/developers/authmanager.md) — authentication lifecycle operations
* [`AuthTable`](/authenticationsystem/developers/authtable.md) — database operations
* [`PlayerData`](/authenticationsystem/developers/playerdata.md) — player data record

## Architecture

```
┌─────────────────────────────────────┐
│       AuthSystemApi.get()           │
│  (static entry point, returns API)  │
└──────────────┬──────────────────────┘
               │
      ┌────────┴────────┐
      ▼                 ▼
┌───────────┐   ┌─────────────┐
│ AuthTable │   │ AuthManager │
│  (DB ops) │   │  (auth ops) │
└───────────┘   └─────────────┘
      ▲                 ▲
      │                 │
 CompletableFuture   Player / state
      │                 │
      ▼                 ▼
┌─────────────┐
│ PlayerData  │
│  (record)   │
└─────────────┘
```

## Core concepts

### AuthSystemApi

The singleton facade. Obtain it with `AuthSystemApi.get()`. Provides access to `AuthTable` and `AuthManager`.

### AuthManager

Handles player authentication: registration, login, password changes, IP checks, premium handling, and authentication state queries.

### AuthTable

Handles all database operations. Every method returns a `CompletableFuture` for asynchronous, non-blocking database access.

### PlayerData

An immutable record representing a player's authentication data: `username`, `UUID`, `hashedPassword`, `lastIp`, `registeredAt`, `premium`.

## Quick reference

| Component       | Responsibility           | Key methods                                                                         |
| --------------- | ------------------------ | ----------------------------------------------------------------------------------- |
| `AuthSystemApi` | Entry point              | `getAuthTable()`, `getAuthManager()`                                                |
| `AuthManager`   | Authentication lifecycle | `register()`, `login()`, `changePassword()`, `isAuthenticated()`, `isWaitingAuth()` |
| `AuthTable`     | Database operations      | `registerPlayer()`, `getPlayerByName()`, `isRegistered()`, `updatePassword()`       |
| `PlayerData`    | Data model               | `username`, `UUID`, `hashedPassword`, `lastIp`, `registeredAt`, `premium`           |

## Thread safety

All `AuthTable` methods are asynchronous and return `CompletableFuture`. They run on a background thread pool. `AuthManager` methods may be synchronous or asynchronous depending on the operation.

Always handle `CompletableFuture` results with `thenAccept`, `thenApply`, or `exceptionally`.

***

> :bulb: **Tip**: Click on each component name above to read its detailed reference page.