Erste SchritteAPI-Schlüssel

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"
    }
  ]
}
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"
  }
}
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"
  }
}
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"
}

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.

idstring
Required

Eindeutige Kennung des API-Schlüssels.

namestring
Required

Anzeigename des API-Schlüssels.

descriptionstring

Optionale Beschreibung, die den Verwendungszweck des Schlüssels erklärt.

key_prefixstring
Required

Nicht sensibler Präfix des Schlüssels, der zur Identifikation angezeigt wird.

permissionsobject
Required

Berechtigungsobjekt für den Schlüssel, einschließlich scopes und rate_limit_per_hour.

last_used_atstring | null

Zeitstempel der letzten erfolgreichen Verwendung des Schlüssels im ISO-8601-Format. Der Wert ist null, wenn der Schlüssel noch nie verwendet wurde.

expires_atstring | null

Ablaufzeitpunkt des Schlüssels im ISO-8601-Format. Der Wert ist null, wenn der Schlüssel nicht abläuft.

is_activeboolean
Required

Gibt an, ob der Schlüssel aktiv ist und für Anfragen verwendet werden kann.

created_atstring
Required

Zeitpunkt der Erstellung des Schlüssels im ISO-8601-Format.

created_bystring
Required

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

query
accountSlugstring
Required

Slug des Kontos, dessen API-Schlüssel Sie auflisten möchten.

Antwortfelder

apiKeysarray
Required

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

body
accountSlugstring
Required

Slug des Kontos, für das der API-Schlüssel erstellt wird.

body
namestring
Required

Anzeigename für den neuen API-Schlüssel.

body
descriptionstring

Optionale Beschreibung, die erklärt, wofür der Schlüssel verwendet wird.

body
environmentstring

Zielumgebung für den Schlüssel. Wenn kein Wert angegeben wird, verwendet Talkturo den Standardwert live.

Allowed values:livetest
body
expiresInDaysnumber

Anzahl der Tage bis zum Ablauf des Schlüssels. Lassen Sie dieses Feld weg, wenn der Schlüssel nicht ablaufen soll.

body
permissionsobject

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

apiKeyobject
Required

Metadaten des neu erstellten API-Schlüssels einschließlich fullKey.

apiKey.fullKeystring
Required

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

path
idstring
Required

Kennung des API-Schlüssels, den Sie aktualisieren möchten.

Body-Parameter

body
namestring

Neuer Anzeigename für den API-Schlüssel.

body
descriptionstring

Neue Beschreibung für den API-Schlüssel.

body
isActiveboolean

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

path
idstring
Required

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 scopes mit ["*"] und rate_limit_per_hour mit 1000.

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.