Settings

Level

level controls how much Identica writes to the logger.

Value	Effect
`0`	errors only
`1`	warnings and errors
`2`	info, warnings, and errors
`3`	adds debug logging
`4`	adds trace logging

level: 3

{
  "level": 3
}

Use 2 for normal operation and 3 or 4 when you are actively debugging routing, pipeline, or provider behavior.

identity

identity controls account UUID assignment and reservation timing.

uniqueIdMode

Danger

Takes: "RANDOM", "OFFLINE", or "PREMIUM"
Current default: "RANDOM"
Affects: how Identica assigns UUIDs to newly discovered accounts

Creates a fresh Identica-owned random UUID for the account. It is not derived from the Minecraft username and does not try to reuse offline-mode or premium/provider UUID conventions.

RANDOM is the recommended mode. It is the most stable option in Identica because it generates an Identica-owned UUID that does not depend on Minecraft's offline-UUID or online-UUID conventions. That makes provider changes and username changes easier to handle inside Identica without losing account continuity.

Derives the UUID from the offline-mode username using the standard OfflinePlayer:<username> namespace. In practice, this means the UUID basis is always the offline username, not provider metadata.

Example: if the player is seen as Steve, Identica generates the same UUID that an offline-mode server would generate for OfflinePlayer:Steve. If that player later changes their username, the offline UUID basis changes with the new username.

Tries to reuse the provider subject UUID first. If that is not usable, Identica falls back to an observed premium UUID when one exists and it is not just the offline-mode UUID for the current username.

In practice, the resolution order is:

use the provider subject if it is already a valid UUID
otherwise use the observed UUID from the platform profile request if it looks like a real premium UUID
otherwise fail to resolve a UUID in this mode

Property	`RANDOM`	`OFFLINE`	`PREMIUM`
Recommended default	Yes	No	No
Generates an Identica-owned UUID	Yes	No	No
Derived from username	No	Yes	No
Uses provider or premium UUID data	No	No	Yes
Stable across username changes inside Identica	Yes	No	Depends on provider
Good for offline-UUID compatibility	No	Yes	No
Easy to migrate to plugins that expect standard Minecraft UUID conventions	No	Yes	Depends on target plugin and provider behavior
May fail when no suitable premium UUID exists	No	No	Yes

RANDOM is usually the best choice for long-term stability inside Identica. OFFLINE mainly exists for compatibility scenarios. PREMIUM is the strictest mode and mostly exists for setups that explicitly need premium/provider UUID continuity.

reservationTtl

Advanced

Takes: a positive duration
Current default: "15m"
Affects: how long reserved account identities and username reservations are kept

This matters during registration and account clearing. If the value is too short, a pending registration can lose its reserved identity. If it is too long, abandoned reservations stay around longer.

identity:
  reservationTtl: "20m"

{
  "identity": {
    "reservationTtl": "20m"
  }
}

sessions

sessions controls live-session behavior for currently connected players.

live session behavior for currently connected players

A session exists while a player is online.

concurrencyPolicy

Warning

Takes: "ALLOW_MULTIPLE", "REPLACE_EXISTING", or "REJECT_NEW"
Current default: "REPLACE_EXISTING"
Affects: the default session-opening policy used by SessionService.open(session)

The policies behave like this:

ALLOW_MULTIPLE: do not reject a new session because another one already exists
REPLACE_EXISTING: remove the existing session and keep the new one
REJECT_NEW: keep the existing session and reject the new one

This is the default policy used when a session opens after authentication, registration, or migration. If one provider needs different behavior, set providers.session.concurrencyPolicy for that provider in the providers config.

activeTtl

Advanced

Takes: a positive duration
Current default: "12h"
Affects: how long live-session cache entries survive between keepalive refreshes while a player is still online

Identica closes the logical session immediately on disconnect. This is not an offline remember-me duration. It only controls the backing cache survival time for active sessions.

sessions:
  concurrencyPolicy: "REPLACE_EXISTING"
  activeTtl: "12h"

{
  "sessions": {
    "concurrencyPolicy": "REPLACE_EXISTING",
    "activeTtl": "12h"
  }
}

listeners

Listener settings control whether selected platform listeners are registered and what priority they use. Platform-specific listener classes and registration details depend on the platform integration in use.

events

Advanced

Takes: a map keyed by fully qualified event class name
Affects: registration and priority for matching listeners

listeners:
  events:
    com.velocitypowered.api.event.connection.PreLoginEvent:
      register: true
      priority: "NORMAL"

{
  "listeners": {
    "events": {
      "com.velocitypowered.api.event.connection.PreLoginEvent": {
        "register": true,
        "priority": "NORMAL"
      }
    }
  }
}

register

Warning

Takes: true or false
Affects: whether that event listener is registered at all

If you set this to false, Identica skips registration for that specific listener. That can be useful for advanced integration experiments, but it can also break parts of the login flow.

priority

Advanced

Takes: "LOWEST", "LOW", "NORMAL", "HIGH", or "HIGHEST"
Affects: the Identica listener priority used for that listener, which is then mapped onto the current platform's event-priority model

If the event entry exists but no priority is set, the current code falls back to NORMAL.

Settings

On this page