Rewards API

Use this instead of the DawnRewards plugin to earn from the Dawn Server Affiliate Program with your own rewards system.

A player earns your server money once both are true:

A claim for them succeeded on your server.
Your heartbeats list them while Dawn sees them playing on your server through the Dawn Client.

#Authentication

Create a plugin token under Plugin credentials at dawn.gg/servers/account. Send it on every request:

http

Authorization: Bearer <plugin token>
Content-Type: application/json

Base URL: https://api.dawn.gg/v2/server-affiliates

Keep the token on your server. Creating a replacement invalidates the old one.

#Heartbeat

POST /heartbeat

Send the full list of online players every 15 seconds. Each heartbeat replaces the previous list for that instance.

json

{
  "instance": "lobby-1",
  "sequence": 1792368000000,
  "players": [
    { "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5" }
  ]
}

Field	Rules
`instance`	One per running server process. Up to 64 characters of `A-Z a-z 0-9 - _`. A random UUID per boot works.
`sequence`	Must be higher than the last accepted one for this instance. Wall-clock milliseconds work across restarts.
`players`	Up to 1000 online player UUIDs.

json

{ "accepted": true, "accountingEnabled": true }

Playtime only counts between heartbeats less than 45 seconds apart.
A network can share one token across up to 512 live instances. Their rosters add up.
Over 1000 players on one process: split them across instances like <instance>-0, <instance>-1, and keep each player in the same part.
An instance that stops reporting is forgotten after an hour.
Unknown fields are rejected.

#Claim

POST /rewards/claim

Call it when a player claims a reward in game. Give the reward only when granted is true.

json

{ "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "period": "daily" }

period is daily or weekly. Days start at 00:00 UTC, weeks on Monday.

The player must be in a heartbeat from the last 45 seconds, so send one before the first claim after they join.

json

{
  "eligible": true,
  "granted": true,
  "alreadyClaimed": false,
  "claimId": "4f1c...",
  "periodStart": "2026-10-17T00:00:00Z",
  "reason": "granted"
}

`reason`	Meaning
`granted`	Claim recorded. Give the reward.
`already_claimed`	Already claimed this period.
`not_on_dawn`	The player is not on the Dawn Client right now.
`not_on_server`	Dawn does not see the player on your server, or your last heartbeat did not list them.
`identity_already_used`	Another account already claimed on your server from this device or IP.
`accounting_disabled`	The program is paused. Nothing is recorded.
`credential_changed`	The token was replaced during the request.

#Presence

GET https://api.dawn.gg/v2/profile/client-presence/<uuid>

Public, no token. Use it to show or hide your rewards menu. The claim is the final check.

json

{ "onDawn": true, "verificationLevel": "session_telemetry", "rewardEligible": false, "maxStalenessSeconds": 90 }

Players with a private Dawn profile always read as onDawn: false.

#Detecting the Dawn Client

On 1.20.5+ you can ask the client for the dawn:client_info cookie. Only the Dawn Client answers it. The value is a version byte followed by two Java modified-UTF-8 strings, brand and ref:

java

player.retrieveCookie(NamespacedKey.fromString("dawn:client_info")).thenAccept(bytes -> {
    if (bytes == null) return; // not the Dawn Client
    try (var in = new DataInputStream(new ByteArrayInputStream(bytes))) {
        byte version = in.readByte();
        String brand = in.readUTF();
        String ref = in.readUTF();
    }
});

#Errors

Failures return { "error": "<message>" }.

Status	Meaning
`400`	Malformed body, instance or UUID.
`401`	Invalid token. Stop sending until it is replaced.
`409`	Sequence not higher than the last one, or too many live instances.
`503`	Temporarily unavailable. Retry with backoff.

#Example

bash

curl https://api.dawn.gg/v2/server-affiliates/heartbeat \
  -H "Authorization: Bearer $DAWN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"instance\":\"lobby-1\",\"sequence\":$(date +%s%3N),\"players\":[{\"uuid\":\"069a79f4-44e9-4726-a5be-fca90e38aaf5\"}]}"

The DawnRewards source is a complete reference.