### CLI: Run HTTP Server (Go)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Starts the Hytale Session Token Broker HTTP server. This command requires the configuration file path.

```bash
go run ./cmd/hytale-session-token-broker -config config.yaml serve
```

--------------------------------

### Start Hytale Session Token Broker HTTP Server (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Starts the HTTP server that exposes the game session minting API. This is the default command if none is specified. It can be run with a default or custom configuration path.

```bash
# Start server (default command if none specified)
go run ./cmd/hytale-session-token-broker -config config.yaml serve

# Output:
# listening on :8080

# With custom config path
go run ./cmd/hytale-session-token-broker -config /path/to/config.yaml serve
```

--------------------------------

### Example Configuration (YAML)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This YAML configuration sets up the broker with HTTP server details, OAuth client credentials, Hytale API endpoints, and account-specific profile UUIDs. It demonstrates how to configure multiple profiles for a single account and specifies a default account.

```yaml
http:
  addr: ":8080"
  bearer_token: ""  # prefer setting HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN instead
store:
  path: "/app/data/state.json"
oauth:
  client_id: "hytale-server"
  scope: "openid offline auth:server"
  device_auth_url: "https://oauth.accounts.hytale.com/oauth2/device/auth"
  token_url: "https://oauth.accounts.hytale.com/oauth2/token"
hytale:
  account_data_base_url: "https://account-data.hytale.com"
  sessions_base_url: "https://sessions.hytale.com"

accounts:
  default:
    profile_uuids:
      - "11111111-1111-1111-1111-111111111111"
      - "22222222-2222-2222-2222-222222222222"

defaults:
  account: "default"
```

--------------------------------

### Example Configuration (Multiple Accounts, YAML)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This YAML configuration illustrates setting up the broker for multiple distinct accounts, each with its own profile UUIDs. It also specifies which account should be considered the default.

```yaml
accounts:
  account1:
    profile_uuids:
      - "11111111-1111-1111-1111-111111111111"
  account2:
    profile_uuids:
      - "22222222-2222-2222-2222-222222222222"

defaults:
  account: "account1"
```

--------------------------------

### CLI: Start Device Login (Go)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Initiates the device login flow for authenticating with Hytale services. This command requires the configuration file path and prints a URL and code for browser-based completion. An optional account name can be provided to log in a second account.

```bash
go run ./cmd/hytale-session-token-broker -config config.yaml auth-login-device

# Login a second account:
go run ./cmd/hytale-session-token-broker -config config.yaml auth-login-device account2
```

--------------------------------

### Broker Initialization (Go)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Demonstrates how to initialize the Hytale Session Token Broker package within a Go application. It covers loading configuration, setting up the store, and starting the broker's HTTP server.

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/hybrowse/hytale-session-token-broker/internal/broker"
    "github.com/hybrowse/hytale-session-token-broker/internal/config"
    "github.com/hybrowse/hytale-session-token-broker/internal/store"
)

func main() {
    // Load configuration
    cfg, err := config.Load("config.yaml")
    if err != nil {
        log.Fatalf("load config: %v", err)
    }

    // Initialize store and broker
    st := store.NewFileStore(cfg.Store.Path)
    br := broker.New(broker.Dependencies{
        Config: cfg,
        Store:  st,
        Now:    time.Now,
    })

    // Start HTTP server
    ctx := context.Background()
    if err := br.Serve(ctx); err != nil {
        log.Fatalf("serve: %v", err)
    }
}
```

--------------------------------

### Programmatic Session Minting (Go)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Shows how to programmatically mint game sessions using the broker's Go package. Examples include minting for any authenticated account, a specific account, or with explicit profile pools.

```go
// Mint session for any authenticated account
resp, err := br.MintGameSession(ctx, "", nil)
if err != nil {
    log.Fatalf("mint: %v", err)
}
log.Printf("session_token: %s", resp.SessionToken)
log.Printf("identity_token: %s", resp.IdentityToken)
log.Printf("expires_at: %s", resp.ExpiresAt)

// Mint session for specific account
resp, err = br.MintGameSession(ctx, "account2", nil)

// Mint session with explicit profile pool
profileUUIDs := []string{
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222",
}
resp, err = br.MintGameSession(ctx, "default", profileUUIDs)
```

--------------------------------

### Minimal Docker Compose Setup for Broker and Server

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This configuration sets up the Hytale Session Token Broker and the Hytale server using Docker Compose. It defines services, images, environment variables, volumes, and ports for both components. The broker is configured to use local data and config files, while the server is set to use the broker for session token generation.

```yaml
services:
  broker:
    image: hybrowse/hytale-session-token-broker:latest
    environment:
      HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN: "" # optional; see secrets example below
    volumes:
      - ./broker-data:/app/data
      - ./config.yaml:/app/config.yaml:ro
    ports:
      - "8080:8080"
    restart: unless-stopped

  hytale:
    image: hybrowse/hytale-server:latest
    environment:
      HYTALE_SESSION_TOKEN_BROKER_ENABLED: "true"
      HYTALE_SESSION_TOKEN_BROKER_URL: "http://broker:8080"
      HYTALE_SESSION_TOKEN_BROKER_TIMEOUT_SECONDS: "10"
    volumes:
      - ./hytale-data:/data
    ports:
      - "5520:5520/udp"
    tty: true
    stdin_open: true
    restart: unless-stopped
```

--------------------------------

### HTTP API: Successful Response (JSON)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Example of a successful JSON response when minting a game session. It includes the session token, identity token, and expiration timestamp.

```json
{
  "session_token": "...",
  "identity_token": "...",
  "expires_at": "..."
}
```

--------------------------------

### Hytale Session Token Broker YAML Configuration Example

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Defines the configuration for the Hytale Session Token Broker, including HTTP server settings, data storage path, OAuth credentials, Hytale API endpoints, and named account configurations with profile pools. Sensible defaults are provided for production use.

```yaml
# config.yaml - Full configuration example
http:
  addr: ":8080"                    # Listen address (default: ":8080")
  bearer_token: ""                 # Optional API authentication (prefer env var)

store:
  path: "/app/data/state.json"     # Persistent state file path

oauth:
  client_id: "hytale-server"
  scope: "openid offline auth:server"
  device_auth_url: "https://oauth.accounts.hytale.com/oauth2/device/auth"
  token_url: "https://oauth.accounts.hytale.com/oauth2/token"

hytale:
  account_data_base_url: "https://account-data.hytale.com"
  sessions_base_url: "https://sessions.hytale.com"

# Named account configurations with profile pools
accounts:
  default:
    profile_uuids:
      - "11111111-1111-1111-1111-111111111111"
      - "22222222-2222-2222-2222-222222222222"
  account2:
    profile_uuids:
      - "33333333-3333-3333-3333-333333333333"

# Default settings
defaults:
  account: "default"               # Default account for CLI commands
  profile_uuids: []                # Fallback profile pool (optional)
```

--------------------------------

### HTTP API: Error Response (Method Not Allowed, JSON)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

JSON error response indicating that the HTTP method used for the request is not allowed for the target endpoint. For example, using GET on a POST-only endpoint.

```json
{"error":"method not allowed"}
```

--------------------------------

### Docker Compose with Secrets for Hytale Session Token Broker (YAML)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

A production-ready Docker Compose setup for the Hytale Session Token Broker and Hytale server, utilizing Docker secrets for secure bearer token management. This configuration ensures that sensitive tokens are not exposed directly in the compose file or environment variables.

```yaml
# docker-compose.yaml with secrets
services:
  broker:
    image: hybrowse/hytale-session-token-broker:latest
    secrets:
      - broker_bearer
    environment:
      HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN_SRC: "/run/secrets/broker_bearer"
    volumes:
      - ./broker-data:/app/data
      - ./config.yaml:/app/config.yaml:ro

  hytale:
    image: hybrowse/hytale-server:latest
    secrets:
      - broker_bearer
    environment:
      HYTALE_SESSION_TOKEN_BROKER_ENABLED: "true"
      HYTALE_SESSION_TOKEN_BROKER_URL: "http://broker:8080"
      HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN_SRC: "/run/secrets/broker_bearer"

secrets:
  broker_bearer:
    file: ./secrets/broker_bearer_token
```

--------------------------------

### Docker Compose with HTTP Bearer Token Secret

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This Docker Compose setup configures the Hytale Session Token Broker and server to use an HTTP bearer token for authentication, recommended via a file-based secret. It specifies secrets for both the broker and server, pointing to a token file. The broker uses `HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN_SRC` to read the token, and the server also uses this for authentication.

```yaml
services:
  broker:
    image: hybrowse/hytale-session-token-broker:latest
    secrets:
      - broker_bearer
    environment:
      HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN_SRC: "/run/secrets/broker_bearer"
    volumes:
      - ./broker-data:/app/data
      - ./config.yaml:/app/config.yaml:ro

  hytale:
    image: hybrowse/hytale-server:latest
    secrets:
      - broker_bearer
    environment:
      HYTALE_SESSION_TOKEN_BROKER_ENABLED: "true"
      HYTALE_SESSION_TOKEN_BROKER_URL: "http://broker:8080"
      HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN_SRC: "/run/secrets/broker_bearer"

secrets:
  broker_bearer:
    file: ./secrets/broker_bearer_token
```

--------------------------------

### CLI: List Profiles (Go)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Lists the available profiles associated with the authenticated account. This command requires the configuration file path.

```bash
go run ./cmd/hytale-session-token-broker -config config.yaml profiles
```

--------------------------------

### Build and Run Hytale Session Token Broker Docker Image (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Commands to build the Hytale Session Token Broker Docker image locally and run it with persistent state and a mounted configuration file. It also shows how to execute a command, like device login, inside a running container.

```bash
# Build the Docker image locally
docker build -t hytale-session-token-broker:local .

# Run with persistent state
docker run --rm \
  -p 8080:8080 \
  -v "$(pwd)/broker-data:/app/data" \
  -v "$(pwd)/config.yaml:/app/config.yaml:ro" \
  hytale-session-token-broker:local

# Run device login inside container
docker exec -it broker-container \
  hytale-session-token-broker -config /app/config.yaml auth-login-device default
```

--------------------------------

### Build Hytale Session Token Broker Docker Image

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This command builds a local Docker image for the Hytale Session Token Broker. It uses `docker build` with a tag `hytale-session-token-broker:local` and assumes the Dockerfile is in the current directory. This allows for local development and testing of the broker.

```sh
docker build -t hytale-session-token-broker:local .
```

--------------------------------

### CLI: Check Auth Status (Go)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Checks the current authentication status of logged-in accounts. This command requires the configuration file path.

```bash
go run ./cmd/hytale-session-token-broker -config config.yaml auth-status
```

--------------------------------

### Authenticate Broker Account via Device Login

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This command executes the device login process for the Hytale Session Token Broker within a running Docker container. It uses `docker exec` to run the broker's authentication command with a specified configuration file. The user is prompted to follow a URL and code in their browser to complete the authentication.

```sh
docker exec -it <broker-container> \
  hytale-session-token-broker -config /app/config.yaml auth-login-device default
```

--------------------------------

### Inspect Broker Profiles

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This command allows inspection of the profiles configured for the Hytale Session Token Broker. It uses `docker exec` to run the broker's profile inspection command, specifying the configuration file. This is useful for understanding the available profiles for authentication.

```sh
docker exec -it <broker-container> \
  hytale-session-token-broker -config /app/config.yaml profiles default
```

--------------------------------

### HTTP API: Mint Game Session (Minimal, curl)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Mints a game session with minimal parameters. This allows any authenticated account to use any available profile. The request body is an empty JSON object.

```bash
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Content-Type: application/json' \
  -d '{}'
```

--------------------------------

### Development Tasks for Hytale Session Token Broker

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This section lists common development tasks for the Hytale Session Token Broker project, executed using a `task` command. These include formatting code (`fmt`), linting (`lint`), running tests (`test`), generating test coverage reports (`cover`), and executing continuous integration checks (`ci`).

```sh
task fmt
task lint
task test
task cover
task ci
```

--------------------------------

### Run Hytale Session Token Broker Docker Container

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This command runs the Hytale Session Token Broker as a Docker container. It maps port 8080 from the host to the container and uses the locally built `hytale-session-token-broker:local` image. The `--rm` flag ensures the container is removed upon exit.

```sh
docker run --rm -p 8080:8080 hytale-session-token-broker:local
```

--------------------------------

### Verify Authentication Status (CLI)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Command to execute within the broker container to check the authentication status of the default account. This is useful for verifying the broker's operational state.

```bash
docker exec -it broker-container \
  hytale-session-token-broker -config /app/config.yaml auth-status default
```

--------------------------------

### CLI: Persist Default Profiles (Go)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Optionally persists a list of default profile UUIDs for the authenticated account. This command requires the configuration file path and a comma-separated list of UUIDs.

```bash
go run ./cmd/hytale-session-token-broker -config config.yaml set-profiles <uuid1,uuid2,uuid3>
```

--------------------------------

### HTTP API: Mint Game Session (Bearer Token, curl)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Mints a game session using an HTTP bearer token for authentication. This method is preferred when the `http.bearer_token` is configured in the broker's settings. The token is provided in the `Authorization` header.

```bash
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

--------------------------------

### Run Broker with Persistent State

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This command runs the Hytale Session Token Broker Docker container while persisting its state on the host machine. It maps port 8080 and mounts a local directory `./local` to `/app/data` inside the container. This ensures that the broker's data is saved across container restarts.

```sh
docker run --rm \
  -p 8080:8080 \
  -v "$(pwd)/local:/app/data" \
  hytale-session-token-broker:local
```

--------------------------------

### Verify Broker Authentication Status

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This command checks the authentication status of the Hytale Session Token Broker within its Docker container. It uses `docker exec` to run the broker's authentication status command, referencing the configuration file. This helps confirm if the previous authentication steps were successful.

```sh
docker exec -it <broker-container> \
  hytale-session-token-broker -config /app/config.yaml auth-status default
```

--------------------------------

### Hytale Session Token Broker: Device Login Authentication (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Initiates the OAuth Device Flow for authenticating with Hytale. It displays a URL and code for browser-based authentication and then polls for authorization. The command can be used for the default account or a specific named account, and is also demonstrated for use within a Docker container.

```bash
# Start device login for default account
go run ./cmd/hytale-session-token-broker -config config.yaml auth-login-device

# Output:
# Visit: https://oauth.accounts.hytale.com/device?user_code=ABCD-EFGH
# Code: ABCD-EFGH
# (complete login in browser)
# Authentication successful for account "default"

# Login a specific named account
go run ./cmd/hytale-session-token-broker -config config.yaml auth-login-device account2

# Docker container usage
docker exec -it broker-container \
  hytale-session-token-broker -config /app/config.yaml auth-login-device default
```

--------------------------------

### HTTP API: Mint Game Session (Fallback Pool, curl)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Mints a game session using a specified pool of profile UUIDs for fallback. If the first profile fails during minting, the broker will attempt to use the subsequent profiles in the provided list.

```bash
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Content-Type: application/json' \
  -d '{"account":"default","profile_uuids":["11111111-1111-1111-1111-111111111111","22222222-2222-2222-2222-222222222222"]}'
```

--------------------------------

### HTTP API: Mint Game Session (Specific Account, curl)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Mints a game session for a specific authenticated account. This is useful when multiple accounts are logged in and you need to select one. The account name is provided in the JSON request body.

```bash
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Content-Type: application/json' \
  -d '{"account":"account2"}'
```

--------------------------------

### Manual Broker Request for Game Session

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This `curl` command demonstrates how to manually request a game session from the Hytale Session Token Broker. It sends a POST request to the broker's `/v1/game-session` endpoint with a JSON payload. This is useful for testing the broker's functionality independently.

```sh
curl -sS -X POST http://localhost:8080/v1/game-session \
  -H 'Content-Type: application/json' \
  -d '{}'
```

--------------------------------

### Set Broker Profile Pool

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

This command pins a specific pool of profiles for the Hytale Session Token Broker, ensuring deterministic behavior. It uses `docker exec` to run the broker's `set-profiles` command, providing a comma-separated list of profile UUIDs and the configuration file. This is useful for load balancing or ensuring specific profiles are used.

```sh
docker exec -it <broker-container> \
  hytale-session-token-broker -config /app/config.yaml set-profiles <uuid1,uuid2,uuid3> default
```

--------------------------------

### Docker Compose for Hytale Server Integration (YAML)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

A Docker Compose configuration that integrates the Hytale Session Token Broker with the Hytale server. It sets up persistent storage for the broker, mounts the configuration file, and exposes the necessary ports. The Hytale server is configured to use the broker for session minting.

```yaml
# docker-compose.yaml
services:
  broker:
    image: hybrowse/hytale-session-token-broker:latest
    environment:
      HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN: ""
    volumes:
      - ./broker-data:/app/data          # Persistent state
      - ./config.yaml:/app/config.yaml:ro
    ports:
      - "8080:8080"
    restart: unless-stopped

  hytale:
    image: hybrowse/hytale-server:latest
    environment:
      HYTALE_SESSION_TOKEN_BROKER_ENABLED: "true"
      HYTALE_SESSION_TOKEN_BROKER_URL: "http://broker:8080"
      HYTALE_SESSION_TOKEN_BROKER_TIMEOUT_SECONDS: "10"
    volumes:
      - ./hytale-data:/data
    ports:
      - "5520:5520/udp"
    tty: true
    stdin_open: true
    restart: unless-stopped
```

--------------------------------

### Hytale Session Token Broker Environment Variables (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Configures bearer token authentication for the Hytale Session Token Broker using environment variables. This method is preferred for secure secret management, especially in containerized environments. The token set via environment variables takes precedence over the configuration file.

```bash
# Set bearer token directly (takes precedence over config file)
export HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN="your-secret-token"

# Set bearer token from file (Docker secrets compatible)
export HYTALE_SESSION_TOKEN_BROKER_BEARER_TOKEN_SRC="/run/secrets/broker_bearer"
```

--------------------------------

### Hytale Session Token Broker: List Profiles (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Fetches and lists all available Hytale profiles associated with an authenticated account. This command can be used to retrieve profiles for the default account or a specific named account, displaying their UUIDs and names.

```bash
# List profiles for default account
go run ./cmd/hytale-session-token-broker -config config.yaml profiles

# Output:
# 11111111-1111-1111-1111-111111111111 MyUsername
# 22222222-2222-2222-2222-222222222222 AltProfile

# List profiles for specific account
go run ./cmd/hytale-session-token-broker -config config.yaml profiles account2
```

--------------------------------

### State File Structure (JSON)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Illustrates the structure of the JSON state file used by the broker to persist OAuth tokens and round-robin cursors. This file is crucial for maintaining authentication state across restarts.

```json
{
  "next_account_index": 1,
  "accounts": {
    "default": {
      "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
      "access_token": "eyJhbGciOiJSUzI1NiIs...",
      "access_token_expires_at": "2025-01-15T13:45:00Z",
      "default_profile_uuids": [
        "11111111-1111-1111-1111-111111111111",
        "22222222-2222-2222-2222-222222222222"
      ],
      "next_profile_index": 1
    },
    "account2": {
      "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
      "access_token": "eyJhbGciOiJSUzI1NiIs...",
      "access_token_expires_at": "2025-01-15T14:00:00Z",
      "default_profile_uuids": [],
      "next_profile_index": 0
    }
  }
}
```

--------------------------------

### Set Default Profiles for Hytale Session Token Broker (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Persists a pool of profile UUIDs for an account to be used by the broker for round-robin distribution and automatic fallback when minting sessions. Supports setting single, multiple, or account-specific profiles.

```bash
# Set single default profile
go run ./cmd/hytale-session-token-broker -config config.yaml set-profiles 11111111-1111-1111-1111-111111111111

# Set multiple profiles for round-robin and fallback
go run ./cmd/hytale-session-token-broker -config config.yaml set-profiles \
  11111111-1111-1111-1111-111111111111,22222222-2222-2222-2222-222222222222

# Set profiles for specific account
go run ./cmd/hytale-session-token-broker -config config.yaml set-profiles \
  33333333-3333-3333-3333-333333333333 account2
```

--------------------------------

### Sign Git Commits with DCO

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/CONTRIBUTING.md

This command adds a Developer Certificate of Origin (DCO) sign-off to your Git commit. This is a mandatory step for all contributions, certifying that you have the right to submit the work and that it can be licensed under the repository's license.

```bash
git commit -s
```

--------------------------------

### POST /v1/game-session

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Requests a short-lived Hytale game session token. The broker manages the OAuth refresh tokens and automatically refreshes access tokens when they are close to expiry.

```APIDOC
## POST /v1/game-session

### Description
Mints short-lived `session_token` and `identity_token` for Hytale game servers. The broker manages long-lived OAuth refresh tokens and automatically handles token refreshes.

### Method
POST

### Endpoint
/v1/game-session

### Parameters
#### Query Parameters
None

#### Request Body
- **account** (string) - Optional - The name of the account to mint the session from. If omitted or set to "any", the broker will pick any authenticated account using a round-robin strategy.
- **profile** (string) - Optional - The specific Hytale profile to use within the selected account.

### Request Example
```json
{
  "account": "account1",
  "profile": "default_profile"
}
```

### Response
#### Success Response (200)
- **session_token** (string) - The short-lived session token for the Hytale game.
- **identity_token** (string) - The identity token associated with the session.
- **expires_at** (string) - The RFC3339 timestamp indicating when the tokens expire.

#### Response Example
```json
{
  "session_token": "<your_session_token>",
  "identity_token": "<your_identity_token>",
  "expires_at": "2023-10-27T10:00:00Z"
}
```

#### Error Response (400/401/500)
- **error** (string) - A message describing the error.
```json
{
  "error": "Invalid credentials or account not found."
}
```
```

--------------------------------

### Hytale Session Token Broker: Mint Game Session Token (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Requests a short-lived session token and identity token pair from the Hytale Session Token Broker's /v1/game-session endpoint. Supports optional account and profile targeting, automatic token refresh, and round-robin distribution. It can also authenticate using a bearer token if configured.

```bash
# Minimal request - uses any authenticated account and auto-selects profile
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Content-Type: application/json' \
  -d '{}'

# Response (HTTP 200)
{
  "session_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "identity_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-01-15T12:30:00Z"
}

# Request with specific account
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Content-Type: application/json' \
  -d '{"account":"account2"}'

# Request with profile fallback pool (tries first, then second on failure)
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Content-Type: application/json' \
  -d '{
    "account": "default",
    "profile_uuids": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"
    ]
  }'

# Request with bearer token authentication (when http.bearer_token is configured)
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

# Error response - account not authenticated (HTTP 401)
{"error":"account \"default\" is not authenticated"}

# Error response - re-authentication required (HTTP 401)
{"error":"account \"default\" needs re-authentication (invalid_grant)"}

# Error response - invalid JSON (HTTP 400)
{"error":"invalid json body"}

# Error response - unauthorized bearer token (HTTP 401)
{"error":"unauthorized"}
```

--------------------------------

### Mint Game Session

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Mints a game session token. Supports specifying account and profile UUIDs for fallback or round-robin selection.

```APIDOC
## POST /v1/game-session

### Description
Mints a game session token. You can optionally specify an account and a pool of profile UUIDs. The broker will attempt to mint a session using the provided profiles in order, with fallback and round-robin logic applied based on configuration.

### Method
POST

### Endpoint
/v1/game-session

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **account** (string) - Optional - The name of the account to use for minting the session. If not provided, the default account is used.
- **profile_uuids** (array of strings) - Optional - A pool of profile UUIDs to use for minting. The broker will try these in order, with fallback and round-robin logic.

### Request Example
Minimal (any authenticated account + any profile):
```json
{}
```

Choose a specific account (when multiple are logged in):
```json
{
  "account": "account2"
}
```

Use a pool for fallback (tries first profile, then second if minting fails):
```json
{
  "account": "default",
  "profile_uuids": [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ]
}
```

If `http.bearer_token` is configured:
```sh
curl -sS \
  -X POST http://localhost:8080/v1/game-session \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### Response
#### Success Response (200)
- **session_token** (string) - The generated session token.
- **identity_token** (string) - The generated identity token.
- **expires_at** (string) - The expiration timestamp of the tokens.

#### Response Example
```json
{
  "session_token": "...",
  "identity_token": "...",
  "expires_at": "..."
}
```

#### Error Responses
All error responses are JSON with an `error` field.

- **401 Unauthorized (HTTP bearer token)**
```json
{
  "error": "unauthorized"
}
```

- **401 Unauthorized (account not authenticated)**
```json
{
  "error": "account \"default\" is not authenticated"
}
```

- **401 Unauthorized (re-auth required)**
```json
{
  "error": "account \"default\" needs re-authentication (invalid_grant)"
}
```

- **400 Bad Request (invalid JSON body)**
```json
{
  "error": "invalid json body"
}
```

- **405 Method Not Allowed**
```json
{
  "error": "method not allowed"
}
```
```

--------------------------------

### HTTP API: Error Response (Unauthorized - Account Not Authenticated, JSON)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

JSON error response indicating that a specified account is not currently authenticated with the broker. Re-authentication may be required.

```json
{"error":"account \"default\" is not authenticated"}
```

--------------------------------

### Hytale Session Token Broker: Check Authentication Status (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Displays the current authentication status for a Hytale account, including the expiration time of the access token and any configured default profiles. This command can check the status for the default account or a specified account.

```bash
# Check status of default account
go run ./cmd/hytale-session-token-broker -config config.yaml auth-status

# Output (authenticated):
# account "default": authenticated
# access token expires: 2025-01-15T13:45:00Z
# default profiles: 11111111-1111-1111-1111-111111111111,22222222-2222-2222-2222-222222222222

# Output (not authenticated):
# account "default": not authenticated

# Check specific account
go run ./cmd/hytale-session-token-broker -config config.yaml auth-status account2
```

--------------------------------

### Mint Game Session Token API

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

The `/v1/game-session` endpoint mints short-lived session tokens for Hytale server authentication. It accepts optional account and profile targeting parameters, automatically refreshes OAuth tokens when needed, and supports round-robin distribution across multiple accounts and profiles.

```APIDOC
## POST /v1/game-session

### Description
Mints short-lived session and identity tokens for Hytale game server authentication. Supports targeting specific accounts and profiles, automatic token refresh, and round-robin distribution.

### Method
POST

### Endpoint
/v1/game-session

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **account** (string) - Optional. The name of the account to use for authentication. Defaults to round-robin if not specified.
- **profile_uuids** (array[string]) - Optional. A list of profile UUIDs to try for token minting. The service will attempt them in order and fall back to the next if one fails.

### Request Example
```json
// Minimal request - uses any authenticated account and auto-selects profile
{}

// Request with specific account
{
  "account": "account2"
}

// Request with profile fallback pool
{
  "account": "default",
  "profile_uuids": [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ]
}

// Request with bearer token authentication (when http.bearer_token is configured)
// Note: This is sent via the Authorization header, not the JSON body.
```

### Response
#### Success Response (200)
- **session_token** (string) - The short-lived session token.
- **identity_token** (string) - The short-lived identity token.
- **expires_at** (string) - The ISO 8601 timestamp when the tokens expire.

#### Response Example
```json
{
  "session_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "identity_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-01-15T12:30:00Z"
}
```

#### Error Responses
- **401 Unauthorized** - If the specified account is not authenticated or requires re-authentication.
  ```json
  {"error":"account \"default\" is not authenticated"}
  ```
  ```json
  {"error":"account \"default\" needs re-authentication (invalid_grant)"}
  ```
- **401 Unauthorized** - If using bearer token authentication and the token is invalid.
  ```json
  {"error":"unauthorized"}
  ```
- **400 Bad Request** - If the request body is invalid JSON.
  ```json
  {"error":"invalid json body"}
  ```
```

--------------------------------

### Health Check Endpoint

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

The `/healthz` endpoint provides a simple health check for load balancers and orchestrators to verify the broker is running.

```APIDOC
## GET /healthz

### Description
Provides a simple health check for the Hytale Session Token Broker.

### Method
GET

### Endpoint
/healthz

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -sS http://localhost:8080/healthz
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the service is healthy.

#### Response Example
```json
{
  "ok": true
}
```
```

--------------------------------

### Health Check

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Checks the health status of the Hytale Session Token Broker.

```APIDOC
## GET /healthz

### Description
Checks the health status of the Hytale Session Token Broker.

### Method
GET

### Endpoint
/healthz

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```sh
curl -sS http://localhost:8080/healthz
```

### Response
#### Success Response (200)
Returns an empty response body on success.

#### Response Example
(No body content)
```

--------------------------------

### HTTP API: Error Response (Unauthorized - Re-authentication Required, JSON)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

JSON error response indicating that an account requires re-authentication, often due to an invalid grant. This suggests the existing authentication token has expired or become invalid.

```json
{"error":"account \"default\" needs re-authentication (invalid_grant)"}
```

--------------------------------

### HTTP API: Health Check (curl)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Performs a health check on the running HTTP server. This request should return a success status if the server is operational.

```bash
curl -sS http://localhost:8080/healthz
```

--------------------------------

### Hytale Session Token Broker: Health Check Endpoint (Bash)

Source: https://context7.com/hybrowse/hytale-session-token-broker/llms.txt

Performs a health check on the Hytale Session Token Broker's /healthz endpoint. This is useful for load balancers and orchestrators to verify the service is running and responsive. It expects a JSON response indicating the service's status.

```bash
# Health check request
curl -sS http://localhost:8080/healthz

# Response (HTTP 200)
{"ok":true}
```

--------------------------------

### HTTP API: Error Response (JSON)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Standard JSON format for error responses from the HTTP API. This structure is used for all error conditions.

```json
{"error":"..."}
```

--------------------------------

### HTTP API: Error Response (Unauthorized - Bearer Token, JSON)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

Specific JSON error response indicating unauthorized access when using an HTTP bearer token. This typically means the provided token is invalid or missing.

```json
{"error":"unauthorized"}
```

--------------------------------

### HTTP API: Error Response (Bad Request - Invalid JSON, JSON)

Source: https://github.com/hybrowse/hytale-session-token-broker/blob/main/README.md

JSON error response indicating a bad request due to an invalid JSON body. This occurs when the client sends malformed JSON data in the request payload.

```json
{"error":"invalid json body"}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.