API-Schlüssel
Erstellen, auflisten, aktualisieren und widerrufen Sie API-Schlüssel für den programmatischen Zugriff auf Talkturo — verwalten Sie Scopes, Ablaufdaten und Schlüssel-Lebenszyklus über REST-Endpunkte.
curl -X GET "https://api.talkturo.com/api/api-keys?accountSlug=acme-sales" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.jwt"
{
"apiKeys": [
{
"id": "key_01hxy9p4m6n2s8t4v7w1z3a5bc",
"name": "Production integrations",
"description": "Used by the CRM sync service",
"key_prefix": "tk_live_a1b2c3d4",
"permissions": {
"scopes": ["assistants:*"],
"rate_limit_per_hour": 1000
},
"last_used_at": "2025-01-14T09:22:11.000Z",
"expires_at": "2025-06-01T00:00:00.000Z",
"is_active": true,
"created_at": "2025-01-10T16:40:02.000Z",
"created_by": "usr_7f3c2d1a9b8e6f5d"
}
]
}
{
"error": "Forbidden"
}
curl -X POST "https://api.talkturo.com/api/api-keys" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.jwt" \
-H "Content-Type: application/json" \
-d '{
"accountSlug": "acme-sales",
"name": "Staging workflow runner",
"description": "Used by the staging automation service",
"environment": "test",
"expiresInDays": 90,
"permissions": {
"scopes": ["assistants:*"],
"rate_limit_per_hour": 1000
}
}'
{
"apiKey": {
"id": "key_01hxyb8r2m4q6s7t9v1w3z5acd",
"name": "Staging workflow runner",
"description": "Used by the staging automation service",
"key_prefix": "tk_test_a1b2c3d4",
"permissions": {
"scopes": ["assistants:*"],
"rate_limit_per_hour": 1000
},
"last_used_at": null,
"expires_at": "2025-04-15T00:00:00.000Z",
"is_active": true,
"created_at": "2025-01-15T11:05:42.000Z",
"created_by": "usr_7f3c2d1a9b8e6f5d",
"fullKey": "tk_test_a1b2c3d4kM7xQ2pL9rT5vN8yH3sJ6wF1uB4eC7dG0hK2mP"
}
}
{
"error": "Forbidden"
}
curl -X PATCH "https://api.talkturo.com/api/api-keys/key_01hxyb8r2m4q6s7t9v1w3z5acd" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.jwt" \
-H "Content-Type: application/json" \
-d '{
"name": "Staging workflow runner v2",
"description": "Used by the updated staging automation service",
"isActive": true
}'
{
"apiKey": {
"id": "key_01hxyb8r2m4q6s7t9v1w3z5acd",
"name": "Staging workflow runner v2",
"description": "Used by the updated staging automation service",
"key_prefix": "tk_test_a1b2c3d4",
"permissions": {
"scopes": ["assistants:*"],
"rate_limit_per_hour": 1000
},
"last_used_at": null,
"expires_at": "2025-04-15T00:00:00.000Z",
"is_active": true,
"created_at": "2025-01-15T11:05:42.000Z",
"created_by": "usr_7f3c2d1a9b8e6f5d"
}
}
{
"error": "API key not found"
}
curl -X DELETE "https://api.talkturo.com/api/api-keys/key_01hxyb8r2m4q6s7t9v1w3z5acd" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.jwt"
{
"success": true,
"message": "API key revoked successfully"
}
{
"error": "API key not found"
}
Verwaltung von API-Schlüsseln
Verwalten Sie API-Schlüssel für ein Talkturo-Konto mit REST-Endpunkten, die Schlüssel auflisten, neue Schlüssel erstellen, Metadaten aktualisieren und Zugriff widerrufen. Diese Endpunkte geben Schlüssel-Metadaten für vorhandene Schlüssel zurück und liefern den Klartextwert fullKey nur dann, wenn Sie einen neuen Schlüssel erstellen.
Authentifizieren Sie jede Anfrage mit einem Bearer-JWT und verwenden Sie ein Kontomitglied mit der Rolle Owner oder Admin. Diese Endpunkte akzeptieren keine Authentifizierung per API-Schlüssel.
API-Schlüssel werden gehasht gespeichert. Talkturo speichert nur einen SHA-256-Hash des vollständigen Schlüssels und kann den Klartextschlüssel nach der Erstellung nicht erneut anzeigen.
API-Schlüsselobjekt
Ein API-Schlüsselobjekt beschreibt einen einzelnen Schlüssel, seine Berechtigungen und seinen Lebenszyklusstatus.
Eindeutige Kennung des API-Schlüssels.
Anzeigename des API-Schlüssels.
Optionale Beschreibung, die den Verwendungszweck des Schlüssels erklärt.
Nicht sensibler Präfix des Schlüssels, der zur Identifikation angezeigt wird.
Berechtigungsobjekt für den Schlüssel, einschließlich scopes und rate_limit_per_hour.
Zeitstempel der letzten erfolgreichen Verwendung des Schlüssels im ISO-8601-Format. Der Wert ist null, wenn der Schlüssel noch nie verwendet wurde.
Ablaufzeitpunkt des Schlüssels im ISO-8601-Format. Der Wert ist null, wenn der Schlüssel nicht abläuft.
Gibt an, ob der Schlüssel aktiv ist und für Anfragen verwendet werden kann.
Zeitpunkt der Erstellung des Schlüssels im ISO-8601-Format.
Kennung des Benutzers, der den Schlüssel erstellt hat.
Schlüsselformat und Lebenszyklus
Neue Schlüssel verwenden das Format tk_{environment}_{random}. Talkturo speichert einen SHA-256-Hash und speichert den Klartext nicht.
fullKey wird nur einmal bei der Erstellung zurückgegeben. Wenn Sie diesen Wert verlieren, erstellen Sie einen neuen Schlüssel und widerrufen Sie den alten.
API-Schlüssel auflisten
Rufen Sie die API-Schlüssel eines Kontos ab, um vorhandene Schlüssel, ihre Berechtigungen und ihren Status zu prüfen.
Abfrageparameter
Slug des Kontos, dessen API-Schlüssel Sie auflisten möchten.
Antwortfelder
Liste der API-Schlüssel für das angegebene Konto.
API-Schlüssel erstellen
Erstellen Sie einen neuen API-Schlüssel, wenn Sie programmatischen Zugriff für eine Integration oder einen internen Dienst benötigen. Die Antwort enthält fullKey genau einmal.
Body-Parameter
Slug des Kontos, für das der API-Schlüssel erstellt wird.
Anzeigename für den neuen API-Schlüssel.
Optionale Beschreibung, die erklärt, wofür der Schlüssel verwendet wird.
Zielumgebung für den Schlüssel. Wenn kein Wert angegeben wird, verwendet Talkturo den Standardwert live.
livetestAnzahl der Tage bis zum Ablauf des Schlüssels. Lassen Sie dieses Feld weg, wenn der Schlüssel nicht ablaufen soll.
Berechtigungen für den Schlüssel. Wenn kein Wert angegeben wird, verwendet Talkturo standardmäßig scopes mit ["*"] und rate_limit_per_hour mit 1000.
Antwortfelder
Metadaten des neu erstellten API-Schlüssels einschließlich fullKey.
Vollständiger Klartext-API-Schlüssel. Dieser Wert wird nur in der Erstellungsantwort zurückgegeben.
API-Schlüssel aktualisieren
Aktualisieren Sie den Namen, die Beschreibung oder den Aktivstatus eines vorhandenen API-Schlüssels, ohne einen neuen Schlüssel auszustellen.
Pfadparameter
Kennung des API-Schlüssels, den Sie aktualisieren möchten.
Body-Parameter
Neuer Anzeigename für den API-Schlüssel.
Neue Beschreibung für den API-Schlüssel.
Setzen Sie diesen Wert auf false, um den Schlüssel zu deaktivieren, oder auf true, um ihn erneut zu aktivieren.
API-Schlüssel widerrufen
Widerrufen Sie einen API-Schlüssel dauerhaft, wenn er nicht mehr benötigt wird oder kompromittiert wurde.
Pfadparameter
Kennung des API-Schlüssels, den Sie widerrufen möchten.
Hinweise zu Berechtigungen
Berechtigungen steuern, was ein API-Schlüssel tun darf und wie häufig er verwendet werden kann. Jeder Schlüssel unterstützt scopes und rate_limit_per_hour.
- Wildcard-Scopes — Verwenden Sie
*, um alle verfügbaren Scopes zu erlauben. - Präfix-Wildcards — Verwenden Sie Werte wie
assistants:*, um alle Scopes innerhalb eines Präfixes zu erlauben. - Exakte Scopes — Verwenden Sie vollständige Scope-Strings, wenn Sie den Zugriff auf bestimmte Aktionen beschränken möchten.
- Standardwerte — Neue Schlüssel verwenden standardmäßig
scopesmit["*"]undrate_limit_per_hourmit1000.
Vergeben Sie den kleinstmöglichen Scope-Satz für jede Integration. Wenn ein Dienst nur Assistenten lesen oder schreiben muss, beschränken Sie den Schlüssel auf die benötigten Scopes, statt globalen Zugriff zu gewähren.