Authentifizierung

Sichern Sie den Zugriff auf Talkturo-API und -App mit API-Schlüsseln, Bearer-Tokens, unterstützten Anmeldemethoden, Scopes und Key-Management-Flows.

curl -X POST https://api.talkturo.com/api/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.chen@acme.com",
    "password": "Str0ngPassw0rd!"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6InRhbGt0dXJvLWRlc2tvcC1hY2Nlc3MiLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiJ1c2VyX2ExYjJjM2Q0IiwiZW1haWwiOiJqYW5lLmNoZW5AYWNtZS5jb20iLCJyb2xlIjoibWVtYmVyIiwiZXhwIjoxNzI2MjAwMDAwfQ.desktop_signature_example",
  "refresh_token": "rt_desktop_example_f84n2m1q9x7v5k3c8p6z4h2j0s1d9b7",
  "expires_in": 3600,
  "expires_at": 1726200000,
  "user": {
    "id": "user_a1b2c3d4",
    "email": "jane.chen@acme.com"
  }
}

curl -X POST https://api.talkturo.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "rt_desktop_example_f84n2m1q9x7v5k3c8p6z4h2j0s1d9b7"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6InRhbGt0dXJvLWRlc2tvcC1hY2Nlc3MiLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiJ1c2VyX2ExYjJjM2Q0IiwiZW1haWwiOiJqYW5lLmNoZW5AYWNtZS5jb20iLCJyb2xlIjoibWVtYmVyIiwiZXhwIjoxNzI2MjAzNjAwfQ.desktop_signature_example",
  "refresh_token": "rt_desktop_example_g52p8n4q1x9v6k3c7m2z5h0j4s8d1b6",
  "expires_in": 3600,
  "expires_at": 1726203600,
  "user": {
    "id": "user_a1b2c3d4",
    "email": "jane.chen@acme.com"
  }
}

curl -X POST https://api.talkturo.com/api/auth/sign-out \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "rt_desktop_example_g52p8n4q1x9v6k3c7m2z5h0j4s8d1b6"
  }'

{
  "success": true
}

Die richtige Authentifizierungsmethode wählen

Talkturo verwendet drei Authentifizierungskontexte, und der passende hängt davon ab, was Sie entwickeln. Nutzen Sie eine Supabase-Session in der Web-App, ein Bearer-JWT für die Close-AI-Desktop-App und einen API-Schlüssel für server-to-server-API-Zugriff oder Automatisierungen.

Kontext	Verwendet von	Anmeldedatentyp	Übermittlung
Web-App	Talkturo-Dashboard	Cookie-basierte Supabase-Session	Browser-Session-Cookie
Desktop-App	Close-AI-Desktop-Client	JWT-Access-Token	`Authorization: Bearer access_token`
API-Clients und Automatisierungen	Externe Integrationen, Skripte, Backend-Services	API-Schlüssel	`Authorization: Bearer tk_live_...`

Für die meisten API-Integrationen verwenden Sie einen API-Schlüssel. JWT-Access-Tokens dienen vor allem dem Anmelde-Flow der Desktop-App.

Unterstützte Anmeldemethoden

Talkturo unterstützt mehrere Benutzer-Anmeldemethoden für Dashboard- und App-Zugriff.

Methode	Anwendungsfall	Hinweise
E-Mail und Passwort	Standardmäßige Kontoanmeldung	Für Web- und App-Anmelde-Flows verfügbar
Magic Link	Passwortlose Anmeldung per E-Mail	Verwendet einen einmaligen E-Mail-Link oder OTP-Flow
Google OAuth	Anmeldung über ein soziales Konto	Startet einen OAuth-Anmelde-Flow
Facebook OAuth	Anmeldung über ein soziales Konto	Startet einen OAuth-Anmelde-Flow
TOTP-Multi-Faktor-Authentifizierung	Zusätzlicher Kontoschutz	Funktioniert mit Authenticator-Apps wie Google Authenticator und Authy

Multi-Faktor-Authentifizierung

Talkturo unterstützt zeitbasierte Einmalpasswörter über Authenticator-Apps. Nachdem MFA für ein Konto aktiviert ist, erfordert der Anmelde-Flow zusätzlich zur primären Anmeldemethode einen gültigen TOTP-Code.

API-Schlüssel

API-Schlüssel authentifizieren serverseitige Anfragen an Talkturo-APIs. Sie sind für Backend-Services, geplante Jobs, interne Tools und andere nicht interaktive Clients vorgesehen.

Schlüsselformat

Live-Schlüssel beginnen mit einem sichtbaren Präfix, gefolgt von einem längeren Geheimwert. Test- oder Sandbox-Schlüssel verwenden dieselbe Struktur mit einem anderen Präfix.

Live-Schlüssel-Format: tk_live_XXXXXXXX gefolgt von 48 Zufallszeichen
Test-Schlüssel-Format: tk_test_XXXXXXXX gefolgt von 48 Zufallszeichen

Das sichtbare Präfix hilft Ihnen, einen Schlüssel im Dashboard zu erkennen, ohne das vollständige Geheimnis freizugeben.

API-Schlüssel werden nur einmal bei der Erstellung angezeigt. Speichern Sie den vollständigen Schlüssel in Ihrem Secret Manager, Password Vault oder Ihrer Umgebungskonfiguration, bevor Sie den Erstellungsbildschirm verlassen.

Wie Talkturo Schlüssel speichert

Talkturo speichert nur den SHA-256-Hash des vollständigen Schlüssels. Der Originalwert kann später nicht mehr abgerufen werden.

Das Dashboard zeigt das Schlüsselpräfix, beispielsweise tk_live_a1b2c3d4, damit Sie erkennen können, welcher Schlüssel verwendet wird. Wenn Sie den vollständigen Schlüssel verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.

Einen API-Schlüssel im Authorization-Header senden

Übergeben Sie den vollständigen API-Schlüssel im Authorization-Header mit dem Bearer-Schema.

curl https://api.talkturo.com/api/api-keys \
  -H "Authorization: Bearer tk_live_a1b2c3d4m7np9q4r8s2x6v1k5z0c3j7h9l2p6w8y1t4u6e" \
  -H "Content-Type: application/json"

Wenn die Authentifizierung erfolgreich ist, verarbeitet die API die Anfrage mit den Berechtigungen, die diesem Schlüssel zugeordnet sind.

Fähigkeiten von API-Schlüsseln

Schlüssel können Metadaten und Lifecycle-Kontrollen enthalten, damit Sie sie sicher über Umgebungen hinweg verwalten können.

Name — eine kurze Bezeichnung für den Schlüssel
Description — optionaler Kontext dazu, wer oder was den Schlüssel nutzt
Expiration — ein optionales Ablaufdatum
Revocation — sofortige Ungültigmachung ohne Löschen der zugehörigen Audit-Historie

Wer Schlüssel erstellen und verwalten kann

Workspace-Owner und Admins können API-Schlüssel erstellen, ändern und löschen. Jedes Workspace-Mitglied kann Schlüssel im Dashboard einsehen, einschließlich identifizierender Metadaten wie dem sichtbaren Präfix.

Permission Scopes

API-Schlüssel verwenden Scopes, um zu steuern, worauf eine Anfrage zugreifen kann. Scopes werden im Permissions-Datensatz des Schlüssels gespeichert.

Standard-Scope

Neue Schlüssel haben standardmäßig Vollzugriff.

scopesstring[]

Required

Default value: ["*"]

Gewährt alle Berechtigungen, die dem Schlüssel innerhalb des Workspace zur Verfügung stehen.

Spezifische Scopes

Verwenden Sie engere Scopes, wenn Sie einen Schlüssel auf eine Teilmenge der API beschränken möchten.

kb:readscope

Knowledge-Base-Ressourcen lesen.

kb:writescope

Knowledge-Base-Ressourcen erstellen, aktualisieren oder löschen.

assistants:readscope

Assistenten-Konfiguration und zugehörige Ressourcen lesen.

Spezifische Scope-Namen können demselben Resource-and-Action-Muster wie diese Beispiele folgen.

Wildcard Matching

Scopes unterstützen Wildcard-Prefix-Matching. Ein Scope wie assistants:* matcht jeden Scope, der mit assistants: beginnt.

Das bedeutet, dass ein Schlüssel mit assistants:* Checks für Werte wie assistants:read oder assistants:write erfüllen kann.

Rate Limit

API-Schlüssel enthalten in ihren Permissions-Daten ein Standard-Rate-Limit.

rate_limit_per_hourinteger

Default value: 1000

Maximale Anzahl an Anfragen, die dem Schlüssel pro Stunde erlaubt sind.

Authentifizierung der Desktop-App

Die Close-AI-Desktop-App authentifiziert sich mit Bearer-JWTs statt mit API-Schlüsseln. Die App meldet sich mit Benutzeranmeldedaten an, erhält ein Access Token und ein Refresh Token und sendet das Access Token bei nachfolgenden Anfragen.

Anmelden

Nutzen Sie den Sign-in-Endpoint, um eine E-Mail-Adresse und ein Passwort gegen ein Token-Paar zu tauschen.

Fügen Sie das zurückgegebene Access Token bei geschützten Anfragen dem Authorization-Header hinzu.

Refresh Tokens

Nutzen Sie den Refresh-Endpoint, wenn das Access Token abläuft.

Abmelden

Nutzen Sie den Sign-out-Endpoint, um das aktuelle Token-Set zu widerrufen.

Format des Desktop-Bearer-Tokens

Desktop-Anfragen verwenden dasselbe Bearer-Header-Muster wie API-Schlüssel, aber der Credential-Wert ist das JWT-Access-Token.

curl https://api.talkturo.com/api/close-ai/sessions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6InRhbGt0dXJvLWRlc2tvcC1hY2Nlc3MiLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiJ1c2VyX2ExYjJjM2Q0IiwiZW1haWwiOiJqYW5lLmNoZW5AYWNtZS5jb20iLCJyb2xlIjoibWVtYmVyIiwiZXhwIjoxNzI2MjAzNjAwfQ.desktop_signature_example"

API-Schlüssel verwalten

Sie können API-Schlüssel im Dashboard oder über die REST API verwalten.

Speicherort im Dashboard

Öffnen Sie Workspace und anschließend API Keys, um Schlüssel zu erstellen, zu prüfen, zu widerrufen oder zu löschen.

REST-API-Endpoints

Nutzen Sie diese Endpoints, um das Key Management zu automatisieren.

/api/api-keysGET

API-Schlüssel auflisten, die im aktuellen Workspace verfügbar sind.

/api/api-keysPOST

Einen neuen API-Schlüssel erstellen.

/api/api-keys/{id}PATCH

Metadaten, Ablauf, Scopes oder Widerrufsstatus eines bestimmten Schlüssels aktualisieren.

/api/api-keys/{id}DELETE

Einen API-Schlüssel löschen.

Nur Benutzer mit der Rolle Owner oder Admin können API-Schlüssel erstellen, aktualisieren, widerrufen oder löschen.

Sicherheitspraktiken

Behandeln Sie Talkturo-Credentials als Production Secrets. Die häufigsten Authentifizierungsprobleme entstehen, wenn Schlüssel in Client-Code freigegeben, nicht wiederherstellbare Schlüssel am falschen Ort gespeichert oder breitere Scopes als nötig verwendet werden.

Betten Sie API-Schlüssel nicht in Browser-Code, Mobile Apps oder verteilte Desktop-Binaries ein. Halten Sie Schlüssel auf einem vertrauenswürdigen Server und leiten Sie Anfragen über einen Proxy, wenn eine Client-Anwendung Talkturo-Daten benötigt.

Empfohlene Praktiken

Verwenden Sie API-Schlüssel nur in serverseitigen Umgebungen.
Bevorzugen Sie eng gescopte Schlüssel gegenüber ["*"], wenn ein Workload begrenzten Zugriff braucht.
Setzen Sie ein Ablaufdatum für temporäre Integrationen.
Rotieren Sie Schlüssel bei Eigentümerwechsel oder wenn Sie eine Exposition vermuten.
Widerrufen Sie einen Schlüssel sofort, wenn er in Logs, Screenshots, Commits oder Support-Tickets auftaucht.

Was this page helpful?