API and credentials

Keep privileges separate#

Server licenses authenticate the server. Panel actions also require the appropriate account permissions. Upload-scoped credentials are bound to evidence-upload context and expire; they cannot be used to manage the panel.

Build reliable integrations#

Handle authentication failures, timeouts and rate limits without tight retry loops. Do not automatically retry a financial write when its outcome is unknown. Do not expose authorization headers in browser code, URLs or logs.

Match endpoint, credential and permission#

Different integrations do not share one universal credential. The registered server license authenticates the SaaS database bridge. Component API tokens can require endpoint-specific scopes. A staff browser action requires the signed-in account’s role and permissions, with CSRF protection for relevant mutations. Evidence-upload tokens are restricted to their context, server and request; they are not administrator tokens.

For the built-in bridge, the header shape is shown below. YOUR_SERVER_LICENSE is a placeholder, never a working credential. The resource sends the protocol body itself; adding these headers to an arbitrary JSON payload does not create a valid job. Keep authentication headers in server-to-server traffic, out of browser code, query strings, analytics and shared error traces.

Authorization: Bearer YOUR_SERVER_LICENSE
Content-Type: application/json

• Server license handling

Handle queued results and errors explicitly#

The bridge endpoint accepts POST JSON, not a SQL string or a table name supplied by the browser. A queued or claimed task is still in progress. Inspect the completed result and operation status before telling staff that a player read or balance update succeeded. The HTTP transport response and the job’s final outcome are separate things.

• 401 unauthorized: verify the credential belongs to the selected server and has not been regenerated.
• 403 bridge_disabled, subscription_inactive or permission_denied: check the server’s Tosun Connect card (bridge_disabled means the connection was turned off there), paid status and account permission; another retry does not grant access.
• 405 / 415: check HTTP method and JSON Content-Type. Malformed JSON or unexpected fields must be corrected, not repeatedly resent.
• 429: respect Retry-After when provided and back off. The built-in bridge limits concurrent work and uses increasing delay on failures.
• 503 or a timeout: record a sanitized time and server/request reference; investigate connectivity and provider state.

• Bridge operations and supported errors

Test with the smallest useful operation#

Use a staging server or controlled test character first. Start with one read, verify the returned character and compare the data with the game. The bridge supports a fixed operation list and pagination, not an unrestricted database dump. Keep a request reference so you can distinguish two reads from a retry of the same action.

Log status, duration and a non-secret reference only. Redact tokens and personal player information from public bug reports. Recheck these tests when changing credentials, permissions or the installed package.

Avoid putting the same administrative token in every integration. Where component credentials are available, use the minimum scopes needed and revoke unused credentials. Changing an endpoint or account permission should trigger another authorization test, including the failed path, rather than relying on one successful request recorded months earlier.

1. Confirm success for the intended server and rejection with a wrong or revoked credential.
2. Confirm staff lacking the relevant permission cannot perform the action; do not test on another customer’s server.
3. Verify how your integration displays pending, failed, expired and done jobs. Do not replace those states with a generic success message.
4. For money changes, treat unknown_outcome as requiring investigation. Read the live balance and audit record before considering another write.

• Performance and bounded requests
• Framework compatibility

Separate staff browser requests from the server protocol#

/api/tenant_db_bridge.php is the panel route authenticated by a staff session. It requires POST, application/json, a valid _csrf and an account belonging to the current tenant; its body limit is 4096 bytes. The action can be enqueue or result. Sending a server license here does not establish a browser session. Permission to read does not imply permission to write money; authorization is checked for the operation.

/api/server_db_bridge.php carries resource health, job retrieval and result exchange from the game server. It uses POST JSON and a Bearer server license, with a 65536-byte body limit. A browser cookie or CSRF value does not replace this protocol. Identify the route before debugging: adding one route’s credential to another request will not resolve authentication. Do not imitate the built-in resource protocol with an arbitrary JSON document.

Distinguish accepted requests from completed work#

ok=true can indicate acceptance of an HTTP request without proving that the queued game operation finished. Track the id, operation and status inside request together. pending waits for processing; claimed has been taken by the server. done carries completed work, failed identifies failure and expired identifies a job beyond its lifetime. Keep the same server_id and request_id context when retrieving results.

Do not show success before examining the final status and error. A matching pending request can reuse an existing job; this is not an unlimited permanent guarantee for repeated submissions. In particular, stop further writes when a money operation reports unknown_outcome. A timeout or invalid result does not prove that no balance change occurred. Inspect the live balance, previous target and audit record for that operation; deleting records to retry removes useful evidence.

Keep a developer error report small and sanitized#

For 405 check method, for 415 check JSON Content-Type, and for 400 check valid JSON and allowed fields. On the browser route, investigate the session for 401 and CSRF validation for 419; reopen the page through normal navigation. For 404 verify server and request context without testing another customer’s records. Wait for existing work when receiving 429.

For 503 or an uncertain network result, record time, endpoint, HTTP status, operation and a non-secret reference. The example below is a support note, not a request body. Exclude cookies, Authorization, _csrf, licenses and player data. Fix the responsible authentication or payload stage instead of masking it with rapid retries; begin validation with one controlled read.

Endpoint: /api/tenant_db_bridge.php
Method: POST
HTTP status: 419
Error: csrf_failed
Operation: players.list
Reference: YOUR_REQUEST_REFERENCE
Time: YOUR_ERROR_TIME

Read one player page with two verified JSON bodies#

This example reads the first player page from a browser already signed into your account’s panel. Server 123 and the request ID are fictional: use your own server and request.id from the enqueue response. Replace CURRENT_PAGE_CSRF with the valid value from the current page. It is not a server licence and must not be copied into a support note. Send a same-origin POST with application/json and your browser session. Reading requires servers.manage or players.view; enqueue is rejected in read-only demo mode.

The first body sends only an empty cursor; this operation can return at most 25 records per page. Do not add limit, SQL, a table name, a connection string or money parameters. If the first response is pending, use the second body to inspect that job rather than enqueue another. On done, read request.result.items. If request.result.has_more is true, use request.result.next_cursor in the next deliberate page request. Interpret an empty list only together with its successful completion status. These templates contain no working credentials. Keep the initial test to one read on your own test server; they are not a way to give public browser extensions administrator access.

POST /api/tenant_db_bridge.php
Content-Type: application/json

Enqueue:
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "enqueue",
  "operation": "players.list",
  "params": {"cursor": ""}
}

Result (use request.id from the enqueue response):
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "result",
  "request_id": "00112233445566778899aabbccddeeff"
}

• MySQL bridge
• Panel and account access

Keep an HTTP timeout separate from the job deadline#

Suppose enqueue is accepted at 14:03:10 and request.id is saved, but a later result call loses its network connection. A single panel HTTP request can stop after 12 seconds; the queued job expires 120 seconds after creation. Aborting a browser request does not cancel that server-side job. Do not present “no response” as an expired or failed job result. Preserve the known ID and read result with the same server_id after connectivity returns. The normal panel flow checks a pending result every three seconds; do not add a tight polling loop.

If the read-only players.list job eventually returns expired with request_expired, record the failure, fix connectivity and then start a new deliberate read. For player.money.set, expiry after claimed or an invalid result can produce unknown_outcome: it does not establish that the balance stayed unchanged. Stop further writes and inspect the live balance and existing operation record. Results are not an unlimited archive; expired records are later removed by bounded cleanup. If the record is no longer found, do not guess its outcome by submitting another money change. Retain only a non-secret reference, time, operation and last known status for support.

Illustrative observations; not an API request body:
14:03:10  enqueue accepted; save request.id
14:03:22  HTTP timeout; job outcome is not established
Later     result with the same server_id + request_id

Read:  expired + request_expired -> investigate before a new read
Write: expired + unknown_outcome -> stop writes and reconcile

• MySQL bridge
• Performance and waiting intervals