Einen Spieler mit seinem Lingara-Konto verknüpfen

API-Version 2026-10-virile-dragon

put https://api.getlingara.com/v1/embed/players/{player_ref}/link

Verknüpft einen deiner Spieler mit dem Lingara-Konto, das deiner App gerade Zugriff gewährt hat. Rufe es mit dem delegierten Token auf, das dein Server für dieses Konto erhalten hat, niemals mit dem eigenen Token deines Clients. Ab dann handeln die Tokens des Spielers als das Konto, soweit die Freigabe es erlaubt: Fordere events:read an, sonst erfährst du nach der Verknüpfung nichts mehr über den Spieler. Fertige Pläne wandern ins Konto; ein Plan, der noch geschrieben wird, bleibt, bis du erneut aufrufst. Kann gefahrlos wiederholt werden: Eine Wiederholung antwortet mit existing und verschiebt, was zuvor nicht verschoben werden konnte. Das Verknüpfen kostet dich nichts.

Scopes embed:play

Parameter

Lingara-Versionheaderstringoptional: Die API-Version, unter der diese Anfrage beantwortet wird. Ohne sie erhält ein Zugriffstoken die Version, an die sein Client gebunden ist, und eine Anfrage ohne Token die aktuelle Version. Die Version in Entwicklung ist nur erreichbar, indem man sie hier nennt. Eine unbekannte Version wird mit 400 und dem Code api_version_unknown beantwortet. GET /v1/versions listet die Versionen auf.
player_refpathstringerforderlich: Die player_ref, mit der du die Tokens des Spielers ausgestellt hast, prozentkodiert: guild/42 wird zu guild%2F42.

Antworten

200 Die Verknüpfung des Spielers

statusLinkStatuserforderlich
subjectstringerforderlich: Die lgr_sub_ des Kontos: was die Ereignisse dieses Spielers von nun an tragen.
previous_subjectstringerforderlich: Die lgr_sub_ des Gasts: was die früheren Ereignisse des Spielers behalten. Leite beide an dieselbe player_ref weiter.
linked_atstringerforderlich: Wann die Verknüpfung hergestellt wurde. Bei einer Antwort existing die Zeit des ersten Aufrufs.
scopesarray of stringerforderlich: Das Höchste, was ein Token für diesen Spieler jetzt tragen kann: was das Konto freigegeben hat, aus den Berechtigungen, die ein Spieler-Token tragen kann.
carriedobjecterforderlich: Zeilen, die dieser Aufruf ins Konto verschoben hat, pro Tabelle. Nur Tabellen mit einer Anzahl erscheinen.
keptobjecterforderlich: Zeilen, die dieser Aufruf beim Gast gelassen hat, pro Tabelle: ein Plan, der noch geschrieben wird, oder eine Zeile, die das Konto bereits hatte. Rufe erneut auf, sobald lesson_plans hier einen fertigen Plan hat.

Fehler

402application/json: Der Aufruf eines nutzungsbasiert abgerechneten Clients wurde abgelehnt, bevor er etwas verbraucht hat. spend_cap_reached: Der Client oder sein Konto hat sein monatliches Ausgabenlimit erreicht; erhöhe das Limit auf der Seite Integrationen. metered_billing_inactive: Die Nutzungsabrechnung ist für dieses Konto nicht aktiv; richte sie ein oder aktualisiere die Zahlungsmethode auf der Seite Integrationen.
410application/json: Die API-Version, unter der diese Anfrage beantwortet wird, wurde eingestellt. Sende eine unterstützte Version in Lingara-Version oder binde den Client an eine andere Version.
4XXapplication/json: Die Anfrage wurde abgelehnt. code nennt den Grund, und error beschreibt ihn in Worten.
503application/json · text/plain: Der Dienst ist vorübergehend nicht verfügbar; versuche es nach der in Retry-After angegebenen Anzahl Sekunden erneut. Während Wartungsarbeiten ist der Body reiner Text statt des Fehlerumschlags.
5XXapplication/json: Die Anfrage wurde abgelehnt. code nennt den Grund, und error beschreibt ihn in Worten.

codestringerforderlich: Warum die Anfrage abgelehnt wurde, als stabiler Code, nach dem du verzweigen kannst: zum Beispiel insufficient_scope (403), rate_limited (429) und, bei einem nutzungsbasiert abgerechneten Client, spend_cap_reached (402) und metered_billing_inactive (402).
errorstringerforderlich

Beispiel

curl -X PUT "https://api.getlingara.com/v1/embed/players/$PLAYER_REF/link" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Lieber eine Bibliothek? Siehe den Bereich Bibliotheken.

Weichen eine Übersetzung und die englische Referenz voneinander ab, ist die englische Referenz maßgeblich.