Anmeldung an der API

Für die Nutzung der Syncler API ist in der Regel ein Access Token erforderlich.
Ausnahmen: Die Webhook- und SAP IDoc-Endpunkte können ohne Access Token aufgerufen werden (abhängig von Ihrer Konfiguration, z. B. Signatur/IP-Allowlist).

Überblick

• Authentifizierung: OAuth 2.0-kompatibel (Bearer Tokens)
• Token-Arten:
  • Access Token – kurzlebig, für API-Aufrufe (Authorization Header)
  • Refresh Token – länger lebig (max. 7 Tage) zur Erneuerung von Access Tokens
• Cloud-Hinweis: In der syncler.com-Cloud sind Access Tokens auf Bereiche/Scopes beschränkt (Mandant/Umfang).

1) POST /token – Direktes Access Token

Schneller Token-Erhalt (ohne Refresh Token).

Anfrage (eine der beiden Varianten):

• Benutzername/Passwort (Admin) oder
• client_id / client_secret (aus der Konfiguration)

Antwort: Access Token (ohne Refresh Token).

curl -X POST "https://<BASE_URL>/token" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "<CLIENT_ID>",
        "client_secret": "<CLIENT_SECRET>"
      }'

2) POST /oauth – Access & Refresh Token (empfohlen)

Gibt Access Token, Gültigkeitsdauer und Refresh Token zurück.

Anfrage (eine der beiden Varianten):

• Benutzername/Passwort (Admin) oder
• client_id / client_secret

curl -X POST "https://<BASE_URL>/oauth" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "<CLIENT_ID>",
        "client_secret": "<CLIENT_SECRET>"
      }'

Beispielantwort:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200a1b2..."
}

3) POST /refreshtoken – Access Token erneuern

Erzeugt ein neues Access Token und (innerhalb der Gesamtgültigkeit) ein neues Refresh Token.

curl -X POST "https://<BASE_URL>/refreshtoken" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "<CLIENT_ID>",
        "refresh_token": "<REFRESH_TOKEN>"
      }'

Beispielantwort:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200a1b2..."
}

Wichtig:

• Ein Refresh Token ist maximal 7 Tage gültig.
• Durch wiederholtes Erneuern (Access+Refresh) bleibt der Zugriff dauerhaft erhalten.
• Nach Ablauf der 7 Tage ist erneut ein /oauth-Aufruf erforderlich.
• Verwaltung: Refresh Tokens werden in den internen Parametern gespeichert und können dort eingesehen oder gelöscht werden. Nach dem Löschen ist der jeweilige Refresh Token sofort ungültig.

Access Token verwenden

Senden Sie das Token im Authorization-Header:

curl "https://<BASE_URL>/api/v1/syncs" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/json"