Config and Keys

AsterYggdrasil separates static config from runtime config.

• Static config lives in data/config.toml and controls database, bind address, cache, object storage, and startup-time settings.
• Runtime config lives in the system_config table and controls Yggdrasil policy, public URLs, upload switches, token policy, and signing keys.

Static Config

Example:

[server]
host = "127.0.0.1"
port = 3000
temp_dir = ".tmp"
start_mode = "primary"

[database]
url = "sqlite://asteryggdrasil.db?mode=rwc"

[cache]
enabled = true
backend = "memory"

[object_storage]
backend = "local"
local_root = "storage"

Relative paths resolve against the directory containing data/config.toml. The default local_root = "storage" resolves to data/storage. Textures and uploaded user avatars both use this object storage config.

Yggdrasil Runtime Config

Common keys:

yggdrasil_server_name
yggdrasil_allow_profile_name_login
yggdrasil_allow_skin_upload
yggdrasil_allow_cape_upload
yggdrasil_token_ttl_days
yggdrasil_max_active_tokens
yggdrasil_max_texture_upload_bytes
yggdrasil_max_texture_pixels
yggdrasil_skin_domains
yggdrasil_public_base_url
yggdrasil_texture_public_base_url
yggdrasil_signature_public_key
yggdrasil_signature_private_key

The public texture library also uses runtime config:

texture_library_enabled
texture_library_review_required

Visual captcha for public authentication flows also uses runtime config:

auth_captcha_enabled
auth_captcha_login_required
auth_captcha_register_required
auth_captcha_invitation_accept_required
auth_captcha_register_activation_resend_required
auth_captcha_preset
auth_captcha_ttl_secs
auth_captcha_length
auth_captcha_max_attempts

Admin Config API:

GET    /api/v1/admin/config
GET    /api/v1/admin/config/schema
PUT    /api/v1/admin/config/{key}
DELETE /api/v1/admin/config/{key}
POST   /api/v1/admin/config/yggdrasil/action

Config writes go through typed normalizers and validators. Do not bypass the service layer and write system_config directly.

Public Texture Library Config

texture_library_enabled is the public texture library master switch. When disabled, public texture library entry points, lists, detail pages, copy flow, and report flow should be hidden or disabled by the frontend; backend public texture library APIs also reject related business requests.

texture_library_review_required controls whether publishing requires review:

• true: user submissions enter pending_review and require administrator approval before appearing in the public library.
• false: user submissions become published immediately.

Both settings are exposed through public frontend config so the frontend can control public entry points, footer links, and user-side texture library actions. Do not hard-code this only in the frontend; backend config remains the source of truth.

Visual Captcha Config

auth_captcha_enabled is the master switch. When enabled, captcha can be required separately for these public authentication flows:

• Local password login.
• Public self-registration.
• Invitation acceptance.
• Registration activation email resend.

Captcha challenges are generated by the server. The frontend reads the public captcha policy to decide whether a flow should show the captcha field. Rendering strength is controlled by auth_captcha_preset; allowed values are readable, balanced, and hardened.

Administrators can preview current captcha rendering through the config action:

POST /api/v1/admin/config/auth_captcha/action

public base URL

For normal deployments, configure public_site_url first:

["https://skin.example.com"]

When yggdrasil_public_base_url is not configured, the server derives the Yggdrasil API root and texture URLs from the first valid public_site_url:

https://skin.example.com/api/yggdrasil/textures/{hash}

yggdrasil_public_base_url is an advanced override. It is also a JSON string array:

["https://skin.example.com/api/yggdrasil"]

When configured, the server uses the first valid http/https URL to build texture URLs. Base URLs may include a path:

https://skin.example.com/api/yggdrasil/textures/{hash}

If neither yggdrasil_public_base_url nor public_site_url has a usable value, Yggdrasil profile texture responses return a configuration error. Protocol responses do not emit relative texture URLs.

yggdrasil_texture_public_base_url is an object-storage/CDN direct URL override for publicly readable, privately writable S3 buckets or CDNs. It is a plain string, not an array:

https://cdn.example.com/env/production/textures

When configured, uploaded textures use {yggdrasil_texture_public_base_url}/{storage_key}, such as https://cdn.example.com/env/production/textures/ab/abcdef...png. Default skins are not stored in object storage and still use the Yggdrasil API URL.

If this URL points to an S3 bucket or CDN, the frontend texture preview loads images directly from that domain. The bucket/CDN must allow anonymous GET/HEAD CORS reads from the public site origins in public_site_url. Browser upload CORS is not needed here because uploads always stream from the server to object storage.

skinDomains

yggdrasil_skin_domains is also a JSON string array. It is an extra texture domain allowlist. authlib-injector validates that texture URL hosts are covered by metadata skinDomains.

Rules can be:

• Exact domains, such as skin.example.com.
• Dot-prefixed domains, such as .example.com.

Metadata responses automatically include Mojang's official domains .minecraft.net and .mojang.com, plus the current effective texture URL host. Configure yggdrasil_skin_domains only when allowing additional CDN or external texture domains.

Signing Keys

authlib-injector requires the server to sign some profile properties:

• hasJoined responses.
• profile/{uuid}?unsigned=false responses.

AsterYggdrasil signs with an RSA private key and exposes the public key in metadata.

The private key cannot be changed through the normal config set API. Rotate it with the config action:

POST /api/v1/admin/config/yggdrasil/action

Action type:

rotate_yggdrasil_signature_key

After rotation:

• Newly generated textures properties use the new private key.
• Metadata derives and returns the new public key.
• Existing tokens do not need to be reissued; signatures are generated when profile properties are built and are not stored in tokens.
• If launchers or servers cached old metadata, verification may fail briefly until metadata is fetched again.

Sensitive Config

yggdrasil_signature_private_key is sensitive:

• It cannot be directly changed from the frontend.
• It must not appear in normal API responses, audit details, or error messages.
• It should be changed only through the rotate action.

yggdrasil_signature_public_key mainly exists as a fallback when no private key is available. In normal operation, the public key derived from the private key is authoritative.