🔌 REST API v1

Roblox has no Discord identifiers – the mapping is handled by a linking system like Bloxlink, which players link once (standard in most Roblox Discord communities anyway). The server script resolves the Discord ID via the Bloxlink API and clocks players in and out when they join or leave the game:

-- Server script (ServerScriptService)
local HttpService = game:GetService("HttpService")
local Players = game:GetService("Players")

local API_BASE = "https://shiftwatch.de/api/v1"
local API_KEY = "sk_..."           -- e.g. from a private server module
local BLOXLINK_KEY = "..."         -- Bloxlink server key (Developer API)
local DISCORD_GUILD_ID = "987654321098765432"

-- Resolve the Discord ID of a linked player via the Bloxlink API
local discordIdCache = {}
local function getDiscordId(player)
    if discordIdCache[player.UserId] ~= nil then
        return discordIdCache[player.UserId]
    end
    local ok, res = pcall(function()
        return HttpService:RequestAsync({
            Url = "https://api.blox.link/v4/public/guilds/" .. DISCORD_GUILD_ID
                .. "/roblox-to-discord/" .. player.UserId,
            Method = "GET",
            Headers = { Authorization = BLOXLINK_KEY }
        })
    end)
    local discordId
    if ok and res.Success then
        local data = HttpService:JSONDecode(res.Body)
        discordId = data.discordIDs and data.discordIDs[1] or nil
    end
    discordIdCache[player.UserId] = discordId
    return discordId
end

local function apiPost(path, payload)
    pcall(function()
        HttpService:RequestAsync({
            Url = API_BASE .. path,
            Method = "POST",
            Headers = {
                ["Content-Type"] = "application/json",
                ["Authorization"] = "Bearer " .. API_KEY
            },
            Body = HttpService:JSONEncode(payload)
        })
    end)
end

-- Clock in on join, clock out on leave
Players.PlayerAdded:Connect(function(player)
    local discordId = getDiscordId(player)
    if discordId then
        apiPost("/clock-in", { user_id = discordId })
    end
end)

Players.PlayerRemoving:Connect(function(player)
    local discordId = discordIdCache[player.UserId]
    if discordId then
        apiPost("/clock-out", { user_id = discordId })
    end
end)

-- Heartbeat loop: every 5 minutes for all linked online players
task.spawn(function()
    while true do
        task.wait(300)
        local ids = {}
        for _, player in ipairs(Players:GetPlayers()) do
            local discordId = discordIdCache[player.UserId]
            if discordId then
                table.insert(ids, discordId)
            end
        end
        if #ids > 0 then
            apiPost("/heartbeat", { user_ids = ids })
        end
    end
end)

On Minecraft servers (Paper/Spigot), DiscordSRV provides the link between Minecraft accounts and Discord IDs – players link once via /discord link. A small plugin then clocks them in on join and out on quit:

// Paper/Spigot plugin, DiscordSRV as the account link source
public final class StempeluhrHook implements Listener {

    private static final String API_BASE = "https://shiftwatch.de/api/v1";
    private final String apiKey;   // load from config.yml
    private final HttpClient http = HttpClient.newHttpClient();

    public StempeluhrHook(String apiKey) {
        this.apiKey = apiKey;
    }

    private void apiPost(String path, String json) {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(API_BASE + path))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        http.sendAsync(request, HttpResponse.BodyHandlers.ofString());
    }

    private String getDiscordId(Player player) {
        return DiscordSRV.getPlugin().getAccountLinkManager()
                .getDiscordId(player.getUniqueId());
    }

    @EventHandler
    public void onJoin(PlayerJoinEvent event) {
        String discordId = getDiscordId(event.getPlayer());
        if (discordId != null) {
            apiPost("/clock-in", "{\"user_id\": \"" + discordId + "\"}");
        }
    }

    @EventHandler
    public void onQuit(PlayerQuitEvent event) {
        String discordId = getDiscordId(event.getPlayer());
        if (discordId != null) {
            apiPost("/clock-out", "{\"user_id\": \"" + discordId + "\"}");
        }
    }

    // Heartbeat every 5 minutes for all linked online players
    public void startHeartbeat(JavaPlugin plugin) {
        Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, () -> {
            List<String> ids = new ArrayList<>();
            for (Player player : Bukkit.getOnlinePlayers()) {
                String discordId = getDiscordId(player);
                if (discordId != null) {
                    ids.add(discordId);
                }
            }
            if (!ids.isEmpty()) {
                String json = "{\"user_ids\": [\""
                        + String.join("\", \"", ids) + "\"]}";
                apiPost("/heartbeat", json);
            }
        }, 20L * 60, 20L * 300);
    }
}

You can also use the API from your own Discord bot – for example for voice duty tracking: whoever joins the "on duty" voice channel gets clocked in, whoever leaves gets clocked out. The bot has the Discord IDs right at hand:

const { Client, GatewayIntentBits } = require('discord.js');

const API_BASE = 'https://shiftwatch.de/api/v1';
const API_KEY = process.env.STEMPELUHR_API_KEY;
const DUTY_CHANNEL_ID = '123456789012345678'; // "on duty" voice channel

async function apiPost(path, payload) {
    const res = await fetch(API_BASE + path, {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer ' + API_KEY,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
    });
    return res.json();
}

const client = new Client({
    intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates]
});

// Joining the duty channel clocks in, leaving clocks out
client.on('voiceStateUpdate', async (oldState, newState) => {
    const joined = newState.channelId === DUTY_CHANNEL_ID
        && oldState.channelId !== DUTY_CHANNEL_ID;
    const left = oldState.channelId === DUTY_CHANNEL_ID
        && newState.channelId !== DUTY_CHANNEL_ID;

    if (joined) await apiPost('/clock-in', { user_id: newState.id });
    if (left) await apiPost('/clock-out', { user_id: newState.id });
});

// Heartbeat every 5 minutes for everyone in the duty channel
setInterval(async () => {
    const channel = await client.channels.fetch(DUTY_CHANNEL_ID);
    const ids = [...channel.members.keys()];
    if (ids.length > 0) {
        await apiPost('/heartbeat', { user_ids: ids });
    }
}, 5 * 60 * 1000);

client.login(process.env.DISCORD_TOKEN);

For scripts, cron jobs, custom tools or a kiosk terminal, a minimal Python client is all you need:

import os
import requests

API_BASE = "https://shiftwatch.de/api/v1"

session = requests.Session()
session.headers.update({
    "Authorization": "Bearer " + os.environ["STEMPELUHR_API_KEY"]
})

def clock_in(user_id):
    return session.post(API_BASE + "/clock-in",
                        json={"user_id": user_id}).json()

def clock_out(user_id):
    return session.post(API_BASE + "/clock-out",
                        json={"user_id": user_id}).json()

def heartbeat(user_ids):
    return session.post(API_BASE + "/heartbeat",
                        json={"user_ids": user_ids}).json()

def status(user_id):
    return session.get(API_BASE + "/status/" + user_id).json()

# Example: clock a user in and show the running session
print(clock_in("123456789012345678"))
print(status("123456789012345678"))