Dokumentation

Öffentliche API

Die 2FA-Konten eines Teams auflisten und deren TOTP-Codes mit einem eigenen Token aus Ihren Werkzeugen abrufen.

Die API erlaubt einem berechtigten Client, die 2FA-Konten eines Teams aufzulisten und deren TOTP-Codes abzurufen.

export API_URL="https://app.shareauth.net"
export API_TOKEN="1|ihr-sanctum-token"

Verwenden Sie im Produktivbetrieb ausschließlich HTTPS. Anfragen und Antworten sind im JSON-Format.

Authentifizierung

Jeder Aufruf enthält ein Sanctum-Token im Header:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Ein Token in der Anwendung erzeugen

Das ist der empfohlene Weg. Wählen Sie in Ihrem Profil im Abschnitt API-Token die Berechtigungen und die Gültigkeitsdauer; Ihr Passwort wird erneut abgefragt, und das Token wird nur ein einziges Mal angezeigt.

Ein Token über die API erzeugen

curl -X POST "$API_URL/api/tokens/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "passwort",
    "device_name": "mein-konnektor",
    "abilities": ["secrets:list", "secrets:generate"],
    "expires_in_days": 30,
    "code": "123456"
  }'

Der zweite Faktor ist Pflicht, in einer dieser Formen:

  • Konto mit Authenticator-App: der sechsstellige Code in code oder ein Wiederherstellungscode in recovery_code;

  • Konto ohne Authenticator-App: Der erste Aufruf ohne code erzeugt nichts. Er antwortet mit 409 und sendet einen sechsstelligen Code per E-Mail:

    {
      "message": "Wir haben Ihnen einen sechsstelligen Code per E-Mail geschickt. Senden Sie diese Anfrage erneut mit dem Code als confirmation_code.",
      "confirmation_required": true
    }
    

    Senden Sie dieselbe Anfrage erneut mit diesem Code in confirmation_code. Er gilt nur einmal und läuft nach 15 Minuten ab.

Antwort:

{
  "token": "1|abcdefghijklmnopqrstuvwxyz",
  "abilities": ["secrets:list", "secrets:generate"],
  "expires_at": "2026-11-18T10:00:00.000000Z",
  "user": {
    "id": 12,
    "name": "Alice",
    "email": "[email protected]"
  }
}

Behandeln Sie dieses Token wie ein Geheimnis.

Berechtigungen und Gültigkeitsdauer

BerechtigungGewährt Zugriff auf
secrets:listdie Liste der 2FA-Konten und die Details eines Kontos
secrets:generateden aktuellen Code eines Kontos
teams:readdie Teams, ihre Mitglieder und den Wechsel des aktiven Teams
audit:readdas Zugriffsprotokoll (Eigentümer des Teams)
integrations:managedie Messaging-Integrationen (Eigentümer des Teams)

Ohne abilities erhält das Token alle fünf Berechtigungen: Fordern Sie nur die an, die Ihr Werkzeug braucht. expires_in_days ist 1, 7, 30 oder 90, standardmäßig 30. Ein Konto hat höchstens zehn aktive Token; abgelaufene Token werden automatisch entfernt, die übrigen lassen sich im Profil widerrufen.

Geheimnisse und Teams anlegen, bearbeiten oder löschen geschieht in der Anwendung: Kein Token kann diese Rechte erhalten.

Aktives Team

Die zurückgegebenen Codes gehören stets zum aktiven Team der Nutzerin oder des Nutzers.

Erreichbare Teams auflisten:

curl "$API_URL/api/v1/teams" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Aktives Team wechseln (Berechtigung teams:read):

curl -X POST "$API_URL/api/v1/teams/42/switch" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

2FA-Konten auflisten

curl "$API_URL/api/v1/secrets" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Gekürzte Antwort:

{
  "data": [
    {
      "id": 7,
      "name": "GitHub production",
      "issuer": "GitHub",
      "digits": 6,
      "period": 30
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "remaining": 9
  }
}

Der TOTP-Seed ist in keiner Antwort enthalten.

Einen Code abrufen

Verwenden Sie die von der Liste zurückgegebene Kennung:

curl -X POST "$API_URL/api/v1/secrets/7/generate" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Antwort:

{
  "data": {
    "secret_name": "GitHub production",
    "code": "123456",
    "next_code": "654321",
    "time_remaining": 18,
    "period": 30,
    "expires_at": "2026-08-13T12:00:30.000000Z"
  }
}

Jede Erzeugung wird im Zugriffsprotokoll des Teams festgehalten. Protokollieren Sie den Code nicht auf der Clientseite.

Zugriffsprotokoll

Dem Eigentümer des aktiven Teams vorbehalten, mit einem Token, das die Berechtigung audit:read hat. Das Protokoll umfasst die Website, die API und die Messaging-Bots.

curl "$API_URL/api/v1/access-logs?channel=slack&limit=50" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Optionale Filter:

ParameterWerte
secret_idKennung eines Geheimnisses des Teams
actionlist, view oder generate
channelweb, api, slack, discord oder teams
limitvon 1 bis 500, standardmäßig 100

Antwort:

{
  "data": [
    {
      "id": 412,
      "actor": {
        "id": null,
        "name": "sam",
        "email": null,
        "external_id": "U04ABCDEF",
        "verified": false,
        "deleted": false
      },
      "bot_integration_id": 3,
      "secret": { "id": 7, "name": "GitHub production", "deleted": false },
      "action": "generate",
      "channel": "slack",
      "ip_address": null,
      "occurred_at": "2026-10-19T09:41:00.000000Z"
    }
  ],
  "meta": {
    "total": 1,
    "disclosures": 1,
    "visible_since": "2026-07-21T00:00:00.000000Z",
    "hidden": 0
  }
}
  • actor.verified ist bei einem Bot false: Name und external_id sind die von der Plattform gemeldeten, ohne Share-Auth-Konto dahinter. actor.deleted kennzeichnet ein inzwischen gelöschtes Konto.
  • meta.visible_since ist der Beginn des mit dem Tarif lesbaren Zeitraums (7 Tage im Tarif Kostenlos, 90 im Tarif Team), null im Tarif Business. meta.hidden zählt ältere Einträge, die aufbewahrt, aber ausgeblendet sind.

Fehler

StatusBedeutung
401Token fehlt oder ist ungültig
403Zugriff verweigert oder Geheimnis außerhalb des aktiven Teams
404Ressource nicht gefunden
422ungültige Daten, fehlendes Team oder Code nicht erzeugbar
429Grenze von 60 Anfragen pro Minute überschritten

Ein Validierungsfehler hat in der Regel diese Form:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

MCP-Konnektor

Der MCP-Konnektor gibt KI-Assistenten (ChatGPT, Codex, Claude und weiteren MCP-Clients) zwei Werkzeuge: die 2FA-Konten des Teams auflisten und den aktuellen Code abrufen. Er liest oder liefert niemals das TOTP-Geheimnis, und jeder abgerufene Code erscheint im Zugriffsprotokoll. Er authentifiziert sich mit einem Token, das auf secrets:list und secrets:generate beschränkt ist.

Der Konnektor wird auf der Seite KI-Agenten (MCP) ausführlich vorgestellt. Sein Quellcode ist öffentlich auf GitHub, ebenso wie der des 2FA-Skills für Agenten.