How to Integrate an Emulator with retroshelf

Use retroshelf's integration API to link a user's account, identify played games, and send play session history from an emulator, launcher, or device plugin.

Setup5 min

Overview

retroshelf integrations let emulators, launchers, and device plugins send play sessions into a user's shelf. The integration should do three things:

  • Link the user's retroshelf account with a short-code flow.
  • Send play sessions when a game ends, or sync missed sessions later.
  • Include enough game metadata for retroshelf to match the session to the right game.

The developer API reference lists every endpoint with request and response examples, and the retroshelf Postman collection lets you try them.

What to request

Submit the developer integration application to request integration access. Include:

  • Emulator, launcher, or plugin name
  • Project website, GitHub repo, or download page
  • Maintainer name and contact email
  • Supported platforms or firmware
  • Brief description of how you will collect play session data
  • Local testing needs, if any

retroshelf will email the approved client details to the maintainer email on the application.

Authentication

Use the OAuth 2.0 Device Authorization Grant, defined by RFC 8628. This is the right fit for emulators and handheld devices because the user can approve the link on a phone or computer.

1

Request a device code

Call the device-code endpoint with the client ID retroshelf gives you.

Request
POST /api/auth/device/code
Content-Type: application/json

{
"client_id": "rs_your_client_id"
}
2

Show the user code

Display the returned code and verification URL inside your emulator or plugin.

Response
{
"device_code": "internal-device-code",
"user_code": "483921",
"verification_uri": "https://retroshelf.org/link",
"expires_in": 1800,
"interval": 5
}

Tell the user to visit retroshelf.org/link, sign in, and enter the code.

3

Poll for tokens

Poll the token endpoint at the returned interval until the user approves the integration.

Request
POST /api/auth/device/token
Content-Type: application/json

{
"grant_type": "urn:ietf:params:oauth:grant-type:device_code",
"device_code": "internal-device-code",
"client_id": "rs_your_client_id"
}

Store the access token securely. The current plugin flow uses that bearer token for sync-client API calls.

4

Complete the link

After token approval, call completeLink to register or reconnect the emulator installation. Store the returned syncClientId; every sync request must include it.

The current supported platform values are onionos, knulli, muos, rocknix, android, spruceos, batocera, steamos, and nextui.

Request
POST /api/syncClient/completeLink
Authorization: Bearer access_token
Content-Type: application/json

{
"name": "ExampleEmu",
"platform": "muos",
"fingerprint": "stable-device-id",
"deviceSlug": "trimui-smart-pro",
"metadata": {
"version": "1.2.3"
}
}
Response
{
"syncClientId": "sync_client_id",
"lastSyncCursor": null
}

Send play sessions

Send sessions after the user exits a game. If the device was offline, queue sessions locally and retry later with the same session fields.

Request
POST /api/syncClient/syncSessions
Authorization: Bearer access_token
Content-Type: application/json

{
"syncClientId": "sync_client_id_from_completeLink",
"sessions": [
{
"romPath": "steam/367520",
"romName": "Hollow Knight",
"steamAppId": "367520",
"duration": 5400,
"devicePlayedAt": 1781229600,
"platformHint": "steam"
}
]
}
Response
{
"submitted": 1,
"created": 1,
"synced": 1,
"matched": 1,
"unmatched": 0,
"results": []
}

submitted is the number of sessions accepted in the request. created is the number of new raw sessions stored after deduplication. synced is the number accepted for matching in this request, including an idempotent retry that was already stored but still pending.

At minimum, send:

  • syncClientId
  • sessions[].romPath
  • sessions[].duration
  • sessions[].devicePlayedAt

devicePlayedAt is the Unix timestamp, in seconds, when the session started. RetroShelf derives the session end by adding duration.

Send these when available:

  • sessions[].romName
  • sessions[].romHash
  • sessions[].steamAppId for exact native Steam game matching
  • sessions[].platformHint

Game matching

retroshelf first uses steamAppId for exact native Steam game matching. Otherwise, it normalizes romName when present, or the filename from romPath, then searches retroshelf's game catalog. Sessions that cannot be matched are still stored as raw sync sessions. When romHash is a valid MD5, retroshelf may use Hasheous as a final exact-match fallback and retain a successful match for future syncs. platformHint narrows catalog searches but does not override an exact hash match.

Do not block a session just because optional metadata is missing. Send what you know, and retroshelf will preserve the raw data.

Integration checklist

  • Request integration access through the developer integration application.
  • Implement OAuth 2.0 Device Authorization Grant.
  • Store tokens outside public config files.
  • Queue sessions while offline.
  • Retry with the same romPath, devicePlayedAt, and duration values for deduplication.
  • Send MD5 ROM hashes when your platform can compute them.
  • Keep API calls in the background so gameplay is never delayed.

Questions

Do I need a client ID before building an integration?

Submit an integration application with your emulator or app details. Client access is reviewed manually while the integration API is early.

What OAuth flow should an emulator use?

Use the OAuth 2.0 Device Authorization Grant from RFC 8628. It lets the emulator display a short code while the user approves access from a phone or computer.

Do I need perfect game metadata?

No. Send the ROM path, ROM name when available, duration, and played-at timestamp. When an MD5 hash is available, retroshelf may also use Hasheous to identify an otherwise unmatched game.

Related