Authentication

Hytale servers require OAuth2 authentication. This container implements the official Server Provider Authentication Guide for seamless, automated authentication.

How It Works

The container uses OAuth2 Device Code Flow (RFC 8628). On first run, you authorize once, and tokens are automatically managed thereafter.

One auth, used everywhere — The same OAuth token authenticates both the downloader and the game server.

Authentication Flow

First Startup

Container requests a device code from Hytale OAuth
A device authorization URL and code appear in the logs
You complete authorization in your browser
Tokens are saved and used for all subsequent operations

Token Usage

After authorization, tokens are used to:

Download server files via hytale-downloader
Create game sessions for the server
Authenticate the server with Hytale's services

Automatic Refresh

Tokens are automatically refreshed before expiry:

Token	Lifetime	Refresh
OAuth Access Token	1 hour	5 min before expiry
OAuth Refresh Token	30 days	—
Game Session	1 hour	5 min before expiry

Subsequent Restarts

On restart:

Load existing tokens from storage
Refresh if needed
Create a new game session
Start the server

Environment Variables

Variable	Default	Description
`AUTO_REFRESH_TOKENS`	`true`	Refresh tokens before expiry
`AUTOSELECT_GAME_PROFILE`	`true`	Auto-select first profile
`HYTALE_SERVER_SESSION_TOKEN`	(empty)	Pre-provided session token
`HYTALE_SERVER_IDENTITY_TOKEN`	(empty)	Pre-provided identity token

Profile Selection

If your account has multiple game profiles:

Automatic (Default)

With AUTOSELECT_GAME_PROFILE=true, the first profile is selected automatically.

Manual Selection

Set AUTOSELECT_GAME_PROFILE=false:

environment:
  AUTOSELECT_GAME_PROFILE: "false"

Then select a profile:

docker exec -it hytale-server hytale auth profile list
docker exec -it hytale-server hytale auth profile select 1

Profile selection is saved and persists across restarts.

Token Storage

Tokens are stored in /server/.hytale/tokens/ (in the volume):

File	Purpose
`oauth_tokens.json`	OAuth access & refresh tokens
`session_tokens.json`	Game session tokens
`profiles.json`	Cached user profiles
`selected_profile.json`	Currently selected profile

CLI Commands

# Check status
docker exec -it hytale-server hytale auth status

# Re-authenticate
docker exec -it hytale-server hytale auth login

# Refresh tokens
docker exec -it hytale-server hytale auth refresh

# List profiles
docker exec -it hytale-server hytale auth profile list

# Select profile
docker exec -it hytale-server hytale auth profile select 1

# Export tokens
docker exec -it hytale-server hytale auth export --json

# Clear all tokens
docker exec -it hytale-server hytale auth logout

For Hosting Providers

If you manage tokens externally, pass them via environment variables:

environment:
  HYTALE_SERVER_SESSION_TOKEN: "eyJhbGciOi..."
  HYTALE_SERVER_IDENTITY_TOKEN: "eyJhbGciOi..."

The container will skip OAuth and use these tokens directly.

Session tokens expire in 1 hour. Your system must refresh and restart containers with new tokens.

Troubleshooting

Issue	Solution
Device code expired	Restart container for new code
Tokens not persisting	Check volume is mounted correctly
Need to re-authenticate	Run `hytale auth logout` then restart

# Force re-auth
docker exec -it hytale-server hytale auth logout
docker compose restart

API Endpoints

The container implements these Hytale OAuth2 endpoints:

Endpoint	Purpose
`POST /oauth2/device/auth`	Request device code
`POST /oauth2/token`	Exchange/refresh tokens
`GET /my-account/get-profiles`	Get user profiles
`POST /game-session/new`	Create game session
`POST /game-session/refresh`	Refresh game session

Base URLs:

OAuth: https://oauth.accounts.hytale.com
Account: https://account-data.hytale.com
Sessions: https://sessions.hytale.com

Next Steps

Configuration — All settings
CLI Reference — Full CLI documentation
Troubleshooting — Common issues

Authentication

On this page