Authentifizierung
Überblick
Die talent Flow API wird über OAuth 2.0 im Client-Credentials-Flow abgesichert. Sie authentifizieren sich nicht als einzelner Benutzer, sondern als Anwendung: Mit ClientId und ClientSecret fordern Sie einen Access Token an und senden diesen anschließend als Bearer-Token an jeden API-Aufruf.
Kurzfassung: Einmal täglich einen Access Token bei id.talent360.io anfordern, den Token zwischenspeichern und jedem Request als Authorization: Bearer <token> — zusammen mit einem gültigen User-Agent — mitgeben.
Eckdaten auf einen Blick
| Parameter | Wert |
|---|---|
| Grant Type | client_credentials |
| Access Token URL | https://id.talent360.io/oauth/token |
| Audience | https://api.talent360.io/api/v3 |
| Basis-URL der API | https://api.talent360.io/v3 |
| Token-Typ | Bearer |
| Pflicht-Header | Authorization, User-Agent |
Audience ≠ Basis-URL. Die audience (https://api.talent360.io/api/v3) ist ein Bezeichner für die API und enthält /api/v3. Die Basis-URL, gegen die Sie Ihre Requests senden, lautet dagegen https://api.talent360.io/v3 — ohne /api. Die beiden Werte sind bewusst unterschiedlich und dürfen nicht vertauscht werden.
Voraussetzungen
ClientId und ClientSecret — diese erhalten Sie von Ihrem Ansprechpartner bei talent360.
Ein HTTP-Client, der
POST-Requests mitapplication/x-www-form-urlencodedsenden kann.Die Möglichkeit, den Access Token serverseitig sicher zwischenzuspeichern.
Das ClientSecret ist ein Geheimnis. Es darf niemals in Frontend-Code, mobilen Apps, öffentlichen Repositories oder Support-Tickets auftauchen. Der Token-Abruf gehört ausschließlich auf Ihren Server. Bei Verdacht auf Kompromittierung kontaktieren Sie uns bitte umgehend, damit wir die Zugangsdaten austauschen.
Ablauf
sequenceDiagram
participant App as Ihre Anwendung
participant Auth as id.talent360.io
participant API as talent Flow API
App->>Auth: POST /oauth/token (client_credentials)
Auth-->>App: access_token + expires_in
Note over App: Token zwischenspeichern
App->>API: GET /v3/... (Bearer-Token + User-Agent)
API-->>App: 200 OK
Note over App,API: Weitere Requests nutzen denselben Token
Schritt 1: Access Token anfordern
Senden Sie einen POST-Request an die Token-URL. Der Parameter audience ist zwingend erforderlich — ohne ihn erhalten Sie einen Token, der von der API nicht akzeptiert wird.
curl -X POST https://id.talent360.io/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "User-Agent: Mozilla/5.0 (Kundenname)" \
-d "grant_type=client_credentials" \
-d "client_id=IHRE_CLIENT_ID" \
-d "client_secret=IHR_CLIENT_SECRET" \
-d "audience=https://api.talent360.io/api/v3"var http = new HttpClient();
http.DefaultRequestHeaders.UserAgent.ParseAdd("Mozilla/5.0 (Kundenname)");
var response = await http.PostAsync(
"https://id.talent360.io/oauth/token",
new FormUrlEncodedContent(new Dictionary<string, string>
{
["grant_type"] = "client_credentials",
["client_id"] = clientId,
["client_secret"] = clientSecret,
["audience"] = "https://api.talent360.io/api/v3",
}));
response.EnsureSuccessStatusCode();
var token = await response.Content.ReadFromJsonAsync<TokenResponse>();const response = await fetch('https://id.talent360.io/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'User-Agent': 'Mozilla/5.0 (Kundenname)',
},
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.T360_CLIENT_ID,
client_secret: process.env.T360_CLIENT_SECRET,
audience: 'https://api.talent360.io/api/v3',
}),
});
const { access_token, expires_in } = await response.json();import os, requests
response = requests.post(
"https://id.talent360.io/oauth/token",
headers={"User-Agent": "Mozilla/5.0 (Kundenname)"},
data={
"grant_type": "client_credentials",
"client_id": os.environ["T360_CLIENT_ID"],
"client_secret": os.environ["T360_CLIENT_SECRET"],
"audience": "https://api.talent360.io/api/v3",
},
)
response.raise_for_status()
token = response.json()["access_token"]Antwort
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...",
"expires_in": 86400,
"token_type": "Bearer"
}
Das Feld expires_in enthält die Gültigkeitsdauer in Sekunden. Richten Sie Ihr Caching immer an diesem Wert aus und gehen Sie nicht von einer fest verdrahteten Laufzeit aus.
Schritt 2: Token zwischenspeichern und wiederverwenden
Ein Access Token ist mehrere Stunden gültig und soll für alle Requests in diesem Zeitraum wiederverwendet werden. Fordern Sie ihn idealerweise einmal pro Tag an — nicht pro Request und nicht pro Job-Lauf.
Kostenrelevant: Das Freikontingent liegt bei 100 Access Tokens pro Monat und Kunde. Jeder darüber hinausgehende Token wird mit 0,10 € berechnet. Eine Implementierung, die pro API-Aufruf einen neuen Token anfordert, überschreitet das Kontingent bereits nach wenigen Minuten.
Bewährtes Vorgehen:
Token nach dem Abruf im Speicher (oder in einem gemeinsamen Cache) halten und erst erneuern, wenn er abläuft.
Einen Sicherheitspuffer einplanen, z. B. Erneuerung bei einer Restlaufzeit unter 5 Minuten.
Bei mehreren Instanzen oder Workern einen gemeinsamen Token-Cache nutzen, damit nicht jede Instanz einen eigenen Token zieht.
Bei einer
401-Antwort genau einmal einen neuen Token anfordern und den Request wiederholen — niemals in einer Schleife.
Schritt 3: API-Request senden
Als Smoke-Test eignet sich ein lesender Stammdaten-Endpunkt, der keine Daten verändert:
curl -X GET https://api.talent360.io/v3/masterdata/nationalities \
-H "Authorization: Bearer IHR_ACCESS_TOKEN" \
-H "User-Agent: Mozilla/5.0 (Kundenname)" \
-H "Accept: application/json"
Pflicht-Header
| Header | Wert | Erforderlich |
|---|---|---|
| Authorization | Bearer | Immer |
| User-Agent | Gültiger User-Agent, siehe unten | Immer |
| Content-Type | application/json | Bei POST, PUT und PATCH |
| Accept | application/json | Empfohlen |
Der User-Agent
Damit alle Anfragen korrekt verarbeitet werden können, muss zwingend ein gültiger User-Agent gesetzt sein — also einer, wie ihn beispielsweise auch ein Browser mitsenden würde. Requests ohne oder mit ungültigem User-Agent können abgewiesen werden.
Damit wir etwaige Probleme schneller analysieren und Ihren Anfragen zuordnen können, empfehlen wir, den Kundennamen in den User-Agent aufzunehmen — ohne Leerzeichen und ohne Umlaute.
Empfohlene Kombination
User-Agent: Mozilla/5.0 (talent360)
Ersetzen Sie talent360 durch Ihren eigenen Kundennamen, zum Beispiel Mozilla/5.0 (Musterfirma).
Es gelten die allgemeinen Regeln für den User-Agent gemäß HTTP-Spezifikation. Details finden Sie in der MDN-Dokumentation zum User-Agent.
Kontingent und Abrechnung
| Position | Wert |
|---|---|
| Freikontingent Access Tokens | 100 pro Monat und Kunde |
| Jeder weitere Access Token | 0,10 € |
| Empfohlene Abrufhäufigkeit | 1× pro Tag |
Bei korrekter Implementierung mit Token-Caching liegt der tatsächliche Verbrauch bei rund 30 Tokens pro Monat und damit deutlich innerhalb des Freikontingents.
Fehlerbehebung
Typische Ursachen:
Der Access Token ist abgelaufen — fordern Sie einen neuen an.
Der Header ist falsch aufgebaut. Korrekt ist
Authorization: Bearer <token>mit genau einem Leerzeichen und ohne Anführungszeichen.Beim Token-Abruf wurde die
audienceweggelassen. Der Token ist dann zwar technisch gültig, aber nicht für die talent Flow API ausgestellt.
Der Token ist gültig, die Anwendung ist für die angefragte Ressource jedoch nicht berechtigt. Prüfen Sie, ob Sie die richtigen Zugangsdaten verwenden — und melden Sie sich bei uns, wenn die Berechtigung erwartet wird.
Prüfen Sie in dieser Reihenfolge:
grant_typemuss exaktclient_credentialslauten.client_idundclient_secretauf führende oder nachgestellte Leerzeichen prüfen — ein häufiger Fehler beim Kopieren aus E-Mails.audiencemuss exakthttps://api.talent360.io/api/v3lauten (ohne abschließenden Schrägstrich).Der Request muss als
application/x-www-form-urlencodedgesendet werden.
Prüfen Sie, ob ein gültiger User-Agent gesetzt ist. Viele HTTP-Bibliotheken senden entweder gar keinen User-Agent oder einen technischen Standardwert. Setzen Sie ihn explizit — siehe Abschnitt Der User-Agent.
In nahezu allen Fällen liegt die Ursache darin, dass pro Request oder pro Prozessstart ein neuer Token angefordert wird. Führen Sie einen gemeinsamen Token-Cache ein, der sich an expires_in orientiert.
Checkliste vor dem Go-Live
Token wird serverseitig angefordert, das ClientSecret liegt in einer Umgebungsvariable oder einem Secret Store.
Der Token wird zwischengespeichert und auf Basis von
expires_inerneuert.Jeder Request sendet
AuthorizationundUser-Agent.Der User-Agent enthält Ihren Kundennamen ohne Leerzeichen und Umlaute.
Bei
401wird genau einmal ein neuer Token geholt und der Request wiederholt.audienceund Basis-URL sind nicht vertauscht.
