> 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/advanced.md).

# Advanced

Advanced integrations, tips, and best practices for working with the AuthSystem API.

## Best practices

### 1. Always null-check the API

```java
AuthSystemApi api = AuthSystemApi.get();
if (api == null) {
    // AuthSystem is not loaded
    return;
}
```

### 2. Handle CompletableFuture exceptions

```java
authTable.getPlayerByUuid(uuid)
    .thenAccept(data -> {
        // handle success
    })
    .exceptionally(ex -> {
        getLogger().severe("Database error: " + ex.getMessage());
        return null;
    });
```

### 3. Cache the API reference

Don't call `AuthSystemApi.get()` in every method. Cache it during initialization:

```java
private AuthSystemApi api;

@Override
public void onEnable() {
    this.api = AuthSystemApi.get();
}
```

### 4. Use async for database operations

All `AuthTable` methods return `CompletableFuture`. Never block on them with `.join()` or `.get()` on the main server thread.

```java
// Bad - blocks the main thread
PlayerData data = authTable.getPlayerByUuid(uuid).join();

// Good - asynchronous
authTable.getPlayerByUuid(uuid).thenAccept(data -> {
    // handle result on completion thread
});
```

## Detecting AuthSystem at runtime

Use `PluginManager` to check if AuthSystem is installed:

```java
Plugin authSystem = getServer().getPluginManager().getPlugin("AuthSystem");
if (authSystem != null && authSystem.isEnabled()) {
    AuthSystemApi api = AuthSystemApi.get();
    // use the API
}
```

## Shading the API

If you want your plugin to work with or without AuthSystem installed, shade the API:

{% tabs %}
{% tab title="Gradle (Shadow)" %}

```kotlin
tasks.named<com.github.johnrengelman.shadow.ShadowPlugin>("shadowJar") {
    relocate("me.authsystem.api", "your.package.shaded.authsystem.api")
}
```

{% endtab %}

{% tab title="Maven (Shade)" %}

```xml
<relocation>
    <pattern>me.authsystem.api</pattern>
    <shadedPattern>your.package.shaded.authsystem.api</shadedPattern>
</relocation>
```

{% endtab %}
{% endtabs %}

Then use the shaded package in your code.

## Database schema reference

The `auth_players` table:

```sql
CREATE TABLE IF NOT EXISTS auth_players (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(16) NOT NULL,
    uuid VARCHAR(36) NOT NULL UNIQUE,
    password_hash VARCHAR(60) NOT NULL,
    last_ip VARCHAR(45),
    registered_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    premium TINYINT(1) DEFAULT 0
);
```

## Brute-force limits

| Limit      | Scope           | Threshold |
| ---------- | --------------- | --------- |
| Per player | Failed attempts | 5         |
| Per IP     | Failed attempts | 10        |

These are enforced by `AuthManager`. When the threshold is exceeded, the player is kicked or banned based on `auth.too-many-attempts`.

## Timeout configuration

Default authentication timeout: **60 seconds** (`auth.timeout-seconds`).

Premium confirmation window: **10 seconds**.

## Update checker

AuthSystem checks for updates via the Modrinth API. This can be disabled by setting `generic.update-checker: false` in `config.yml`.

## Common integration patterns

### Permission-gated feature

```java
if (api.getAuthManager().isAuthenticated(player) && player.hasPermission("myplugin.feature")) {
    // allow access
}
```

### Auto-login on join (for testing only)

{% hint style="danger" %}
Auto-login bypasses security. Only use this for testing on a local development server.
{% endhint %}

```java
// Not recommended for production
authTable.getPlayerByUuid(player.getUniqueId())
    .thenAccept(data -> {
        if (data.isPresent()) {
            authManager.login(player, "knownPassword");
        }
    });
```

***

> :bulb: **Tip**: When in doubt, check the [Examples](/authenticationsystem/developers/examples.md) page for ready-to-use code patterns.