Für die Anbindung externer Systeme an crm-now xRM steht ein zentraler OAuth2-Endpunkt zur Verfügung. Dieser ermöglicht es Partnern, Access Tokens sicher zu beziehen und diese in weiteren API-Aufrufen zu verwenden. Die nachfolgenden Hinweise erläutern das Verfahren zur Token-Abholung, Token-Validierung sowie die Integration in eigene Skripte.

1. Überblick

Der OAuth2-Endpunkt dient als einheitliche Schnittstelle für alle CRM- und RCA2-Integrationen (VitroConnect). Externe Systeme authentifizieren sich dort mittels Client ID und Client Secret und erhalten ein zeitlich begrenztes Access Token. Dieses Token muss anschließend in jedem API-Aufruf als Bearer-Token (Base64 codiert) mitgegeben werden.

2. Token abholen

Voraussetzungen

• Eine gültige Client ID
• Ein zugehöriges Client Secret
• Beides wird einem Partner von uns auf sicherem Weg zur Verfügung gestellt, ggf. anfragen

Beispiel (curl)

curl --location --request POST 'https://api.i1.crm-now.de/v1/getOauthToken.php' \
--header 'Authorization: Basic <base64encode(urlencode(clientID):urlencode(clientSecret))>'

Beispiel (PHP)

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.i1.crm-now.de/v1/getOauthToken.php',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic <base64encode(urlencode(clientID):urlencode(clientSecret))>'
  ),
));

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Beispielantwort

{
    "access_token": "xxxxxxxx",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "scope": "realm profile email"
}

Hintergrund

Client ID und Client Secret werden gemäß OAuth2-Spezifikation im Basic-Auth-Header übertragen.

Client ID entspricht dem Benutzername, Client Secret dem Passwort.

Beide Werte werden im Header base64-codiert übermittelt.

3. Token validieren

Zur optionalen Überprüfung, ob ein Token gültig ist, kann derselbe Endpunkt mit einem verifytoken Parameter aufgerufen werden.

Beispiel (curl)

curl --location 'https://api.i1.crm-now.de/v1/getOauthToken.php' \
--form 'verifytoken="ACCESS_TOKEN_HERE"'

Beispielantwort

{
    "result": true,
    "message": "token valid"
}

4. Verwendung in eigenen Skripten

Im eigenen Code sollte vor Ausführung einer API-Funktion geprüft werden, ob im Authorization Header ein valides Bearer-Token enthalten ist.

Beispielhafte PHP-Validierung

$validToken = false;
$headers = getallheaders();

if (isset($headers['Authorization'])) {
    $authHeader = $headers['Authorization'];
} elseif (isset($headers['authorization'])) {
    $authHeader = $headers['authorization'];
} else {
    $authHeader = null;
}

if ($authHeader && preg_match('/Bearer\s(\S+)/', $authHeader, $matches)) {
    $token = $matches[1];

    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => 'https://api.i1.crm-now.de/v1/getOauthToken.php',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => array('verifytoken' => $token),
    ));
    $response = json_decode(curl_exec($curl), true);
    curl_close($curl);

    if ($response['result'] === true) {
        $validToken = true;
    }
}

if (!$validToken) {
    http_response_code(401);
    echo json_encode(['error' => 'missing or invalid auth token']);
    exit;
}

Diese Prüfung stellt sicher, dass nur autorisierte Systeme API-Funktionen ausführen können.

Fazit

Der zentrale OAuth2-Endpunkt vereinfacht die sichere Authentifizierung für Integrationen mit crm-now xRM.

Wichtig für eine fehlerfreie Nutzung sind:

• korrekt hinterlegte Client ID und Client Secret
• korrekte Basic-Auth-Kodierung
• Übergabe des Tokens als Bearer-Header
• optionale, aber empfehlenswerte Token-Validierung im eigenen Code

Ablaufdiagramm: Token-Abholung und Token-Verwendung

Checkliste für Integrationspartner

Diese Liste hilft Partnern, die häufigsten Fehler bei der OAuth-Anbindung zu vermeiden.

1. Vorbereitung

• Client ID erhalten
• Client Secret erhalten
• Credentials sicher gespeichert
• Base64 Encoding für clientID:clientSecret korrekt umgesetzt

2. Token-Abholung

• POST-Request an den zentralen OAuth-Endpunkthttps://api.i1.crm-now.de/v1/getOauthToken.php
• Authorization Header im FormatAuthorization: Basic <base64encode(clientID:clientSecret)>
• Kein zusätzlicher Body nötig (reiner Basic-Auth-Token-Request)
• Antwort enthält ein gültiges Access Token im JSON-Format
• Ablaufzeit des Tokens (expires_in) berücksichtigt (Standard: 300 Sekunden)

3. Token-Verwendung

• Bearer-Token wird in jedem API-Aufruf gesetzt:Authorization: Bearer <access_token>
• Keine Übertragung über URL-Parameter
• HTTPS verwendet

4. Token-Validierung (optional aber empfohlen)

• POST-Request mit verifytoken=<token> möglich
• Rückmeldung überprüft (result:true)

5. Serverseitige Prüfung im eigenen System

• Eingehende HTTP-Requests prüfen Header Authorization
• Bearer-Token extrahieren
• Token gegen den OAuth-Endpunkt validieren
• Bei ungültigem Token: Rückgabe von HTTP 401

6. Fehleranalyse

• Fehler 401: Prüfen, ob Bearer-Token im Header vorhanden ist
• Fehler 401 beim Token-Abholen: Base64-Encoding korrekt?
• Token schon abgelaufen?
• Stimmt die Client ID / das Secret?
• HTTP-Proxys entfernen eventuell den Authorization-Header (Apache: SetEnvIf prüfen)