MuchSkills API und API-Zugang

So funktioniert es

Die MuchSkills API nutzt OAuth 2.0 mit dem Client Credentials Grant. Jeder API-Client hat eigene Client ID, eigenes Client Secret und eigene Scopes. So können Sie jeder Integration einen eigenen Client geben und einen davon widerrufen, ohne die anderen zu berühren. Die Basisadresse lautet https://app.muchskills.com.

Bevor Sie beginnen

• In MuchSkills: die Rolle Owner oder Admin, um Clients anlegen zu können.
• Ein Entwickler oder ein Tool, das HTTPS-Anfragen senden kann, zum Beispiel eigener Code, eine Integrationsplattform oder Power Query.
• Der passende Scope. Read für Berichte und Exporte. Write nur, wenn die Integration Daten ändert.
• Ein sicherer Ort für das Secret. Ein Passwortmanager oder Ihr Secrets-Vault. MuchSkills zeigt das Secret nur ein einziges Mal an.
• Die API-Referenz. Sie liegt unter app.muchskills.com/api/docs und lässt sich aufrufen, sobald Sie bei MuchSkills angemeldet sind. Entwickler ohne Login können beim Support Zugang anfragen.

Schritte

In MuchSkills

1. API Access öffnen. Rufen Sie Team/Org › Settings › API Access auf. Sie können auch auf der Seite Integrations auf Go to API Access klicken.
2. Client anlegen. Klicken Sie auf New Client. Tragen Sie im Fenster Create API client unter Name eine Bezeichnung ein, an der Sie den Client wiedererkennen, zum Beispiel Berichts-Pipeline. Aktivieren Sie unter Scopes die Option Read und Write nur, wenn Sie es wirklich brauchen. Klicken Sie dann auf Create Client.

Team/Org › Settings › API Access › New Client.

3. Zugangsdaten kopieren. Das Fenster Copy your credentials zeigt Client ID und Client Secret. Kopieren Sie beide an einen sicheren Ort, bevor Sie auf Done klicken. Das Client Secret wird nur ein einziges Mal angezeigt.

Create API client: 1 Name, 2 Read oder Write, 3 Create Client.

In Ihrer Anwendung

4. Token anfordern. Senden Sie Client ID und Client Secret an den Token-Endpunkt. Der Body muss formularcodiert sein:

curl -X POST https://app.muchskills.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=IHRE_CLIENT_ID" \
  -d "client_secret=IHR_CLIENT_SECRET"

Die Antwort enthält access_token, token_type (Bearer), expires_in in Sekunden und den gewährten scope.

5. API aufrufen. Senden Sie das Token im Header Authorization. Dieser Aufruf liefert die ersten 300 Profile:

curl -X POST "https://app.muchskills.com/api/v2/profile/search?skip=0&limit=300" \
  -H "Authorization: Bearer IHR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

Wenn Sie nur ausgewählte Personen abrufen möchten, schicken Sie {"filters": {"emails": ["anna@yourcompany.com"]}} als Body mit.

6. Durch die Ergebnisse blättern. Jede Antwort enthält ein pagination-Objekt mit dem Wert total. Erhöhen Sie skip jeweils um Ihr limit und wiederholen Sie den Aufruf, bis Sie alle Einträge haben. limit darf höchstens 300 betragen.

Prüfen, ob es funktioniert hat

• Die Token-Anfrage liefert 200 und ein access_token zurück.
• Der Suchaufruf liefert 200 zurück, die Profile stehen in data und der Wert total in pagination.
• Auf der Seite API Access steht in der Spalte Last used des Clients ein Zeitpunkt statt Never.

Ihr Nutzen

• Ihre Daten in Ihren Tools. Profile, Kompetenzen, Zertifikate, Ziele und Verfügbarkeit fließen in Berichte, Data Warehouses und andere Systeme.
• Daten ohne Abtippen einspielen. Übertragen Sie Zertifikate, Kompetenzstufen, Ziele und Abwesenheiten direkt aus den Systemen, in denen sie entstehen.
• Kontrolle je Integration. Jeder Client hat einen eigenen Scope und lässt sich einzeln widerrufen.

Wichtig zu wissen

Verfügbare Aufrufe. Die API hat 22 Endpunkte. Alle folgenden Pfade beginnen mit https://app.muchskills.com.

Personen werden per E-Mail identifiziert. Verwenden Sie die Adresse, mit der sich die jeweilige Person bei MuchSkills anmeldet.

Die Suche läuft über POST. Auf einen GET antwortet POST /api/v2/profile/search mit 404. Die Paging-Werte skip und limit übergeben Sie in der URL, die Filter im JSON-Body.

Tokens gelten etwa eine Stunde. Ein Refresh Token gibt es nicht. Fordern Sie ein neues Token an, wenn das alte abläuft oder ein Aufruf mit 401 antwortet.

Schreiben erfordert den Write-Scope. Ein Client mit nur dem Read-Scope oder ein altes Organisations-Token erhält bei Schreibaufrufen 403.

Abwesenheiten werden komplett ersetzt. PUT /api/v2/profile/{email}/pto ersetzt alle Abwesenheiten der Person, eine leere Liste löscht sie. Verwaltet eine HR-Integration die Abwesenheiten Ihrer Organisation, antwortet der Aufruf mit 403: Ändern Sie Abwesenheiten dann im HR-System.

Kompetenzen werden auf einer Skala von 1 bis 9 bewertet. 1 bis 3 entspricht Beginner, 4 bis 6 Intermediate und 7 bis 9 Expert. Profile enthalten die Selbsteinschätzung der Person und, sofern eine Führungskraft sie validiert hat, die validierte Stufe.

Private Dateien erfordern einen Header. Zertifikats- und Ausbildungsdateien sind privat. Antworten enthalten ein auth-Objekt mit dem Header, den Sie beim Öffnen mitsenden. Er läuft ab; mit GET /api/v2/auth/file-validation-header erhalten Sie einen neuen.

Anfragelimits. Zu viele Anfragen in kurzer Zeit werden mit 429 Too Many Requests beantwortet. Warten Sie und versuchen Sie es mit wachsender Pause erneut, zum Beispiel nach 1, 2, dann 4 Sekunden. Die Ziel-Aufrufe erlauben eine Anfrage pro Sekunde und Token.

Legacy-Tokens werden eingestellt. Gibt es in MuchSkills für Ihre Site noch ein altes Organisations-Token, erscheint auf der Seite Integrations der Hinweis A legacy API token is still active for this site. Stellen Sie jede Integration auf einen API-Client um.

Widerrufen ist endgültig. Revoke auf der Seite API Access sperrt die Zugangsdaten eines Clients sofort und lässt sich nicht rückgängig machen.

Fehlerbehebung