Authentifizierung

Sichere API-Authentifizierung mit OAuth2 Client Credentials

Übersicht

Die SteuerMappePro API verwendet OAuth 2.0 Client Credentials Flow für Machine-to-Machine (M2M) Authentifizierung. Dieser Flow ist optimal für Server-zu-Server-Kommunikation ohne Benutzerinteraktion.

OAuth 2.0

Industrie-Standard für sichere API-Authentifizierung

TLS/HTTPS

Alle Anfragen verschlüsselt über HTTPS (TLS 1.2+)

JWT Tokens

Signierte JSON Web Tokens mit 1 Stunde Gültigkeit

API-Zugangsdaten erhalten

API-Zugangsdaten werden auf Projekt-Ebene erstellt. Jedes Projekt erhält eigene Credentials mit definierten Berechtigungen (Scopes).

Wie erhalte ich Zugangsdaten?

Kontaktieren Sie Ihren SteuerMappePro Administrator. Dieser kann in der Admin-Konsole API-Clients für Ihr Projekt erstellen und Ihnen die Credentials bereitstellen.

Sie erhalten:

Client ID: Eindeutige Kennung Ihres API-Clients (z.B. proj_datev_2024_abc123)
Client Secret: Geheimer Schlüssel (64 Zeichen) - wird nur einmal bei Erstellung angezeigt!
Scopes: Berechtigungen für Ihren API-Client (z.B. batches:write batches:read)

Access Token anfordern

Fordern Sie einen Access Token an, um API-Anfragen zu authentifizieren:

Endpoint

POST https://api.steuermappe-pro.de/v1/oauth/token

Request Body

{
  "grant_type": "client_credentials",
  "client_id": "proj_datev_2024_abc123",
  "client_secret": "your_secret_key_here",
  "scope": "batches:write batches:read results:read"
}

Beispiel: cURL

curl -X POST https://api.steuermappe-pro.de/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "proj_datev_2024_abc123",
    "client_secret": "your_secret_key",
    "scope": "batches:write batches:read results:read"
  }'

Beispiel: TypeScript

async function getAccessToken() {
  const response = await fetch('https://api.steuermappe-pro.de/v1/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: process.env.STEUERMAPPE_CLIENT_ID,
      client_secret: process.env.STEUERMAPPE_CLIENT_SECRET,
      scope: 'batches:write batches:read results:read'
    })
  });

  if (!response.ok) {
    throw new Error(`Token request failed: ${response.status}`);
  }

  const data = await response.json();
  return data.access_token;
}

Antwort (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6InByb2pfZGF0ZXZfMjAyNF9hYmMxMjMiLCJwcm9qZWN0SWQiOiJwcmpfMTIzIiwib3JnYW5pemF0aW9uSWQiOiJvcmdfYWJjIiwidXNlcklkIjoidXNlcl94eXoiLCJzY29wZXMiOlsiYmF0Y2hlczp3cml0ZSIsImJhdGNoZXM6cmVhZCIsInJlc3VsdHM6cmVhZCJdLCJwYXJ0bmVyQ29kZSI6IkFCQzEyMyIsImF1ZCI6InN0ZXVlcm1hcHBlLWFwaSIsImV4cCI6MTY5NjU5ODQwMH0...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "batches:write batches:read results:read",
  "project": {
    "id": "prj_123",
    "name": "DATEV Integration 2024",
    "organization_id": "org_abc",
    "partner_code": "ABC123"
  }
}

Token-Gültigkeit

Der Access Token ist 1 Stunde (3600 Sekunden) gültig. Fordern Sie bei Ablauf einen neuen Token an. Token Refresh wird aktuell nicht unterstützt.

Access Token verwenden

Fügen Sie den Access Token als Authorization Header zu jeder API-Anfrage hinzu:

cURL Beispiel

curl -X GET https://api.steuermappe-pro.de/v1/batches/b_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

TypeScript Beispiel

const accessToken = await getAccessToken();

const response = await fetch(
  'https://api.steuermappe-pro.de/v1/batches/b_abc123',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  }
);

const batch = await response.json();

Scopes (Berechtigungen)

Scopes definieren die Berechtigungen Ihres API-Clients:

Scope	Beschreibung
batches:write	Batch-Verarbeitungen erstellen
batches:read	Batch-Status und Fortschritt abrufen
results:read	Verarbeitungsergebnisse herunterladen
webhooks:manage	Webhooks erstellen und verwalten

Minimale Berechtigungen

Fordern Sie nur die Scopes an, die Sie tatsächlich benötigen (Principle of Least Privilege). Standard-Scopes sind: batches:write batches:read results:read

Sicherheitsrichtlinien

Client Secret schützen

✓ Niemals Client Secret in Client-Side Code (Browser, Mobile Apps) verwenden
✓ Secret in Umgebungsvariablen oder Secret Manager speichern
✓ Secret nicht in Git Repositories committen
✓ Secret regelmäßig rotieren (alle 90 Tage empfohlen)

HTTPS verwenden

✓ Alle API-Anfragen müssen über HTTPS erfolgen
✓ HTTP-Anfragen werden automatisch abgelehnt (403 Forbidden)
✓ TLS 1.2 oder höher erforderlich

Token-Verwaltung

✓ Access Token sicher speichern (Memory, nicht Disk)
✓ Token-Ablauf überwachen und rechtzeitig erneuern
✓ Keine Tokens in Logs oder Error Messages ausgeben

Kompromittierte Credentials

Falls Ihre Credentials kompromittiert wurden, kontaktieren Sie sofort Ihren Administrator zur Sperrung und Neuausstellung: security@steuermappe-pro.de

Fehlerbehandlung

Status Code	Fehler	Bedeutung
400	invalid_request	Ungültiges Request-Format
401	invalid_client	Ungültige Client ID oder Secret
401	invalid_token	Token abgelaufen oder ungültig
403	insufficient_scope	Fehlende Berechtigung (Scope)
429	rate_limit_exceeded	Rate Limit überschritten

Fehler-Antwort Format

{
  "error": "invalid_client",
  "error_description": "Client authentication failed. Invalid client_id or client_secret.",
  "error_uri": "https://docs.steuermappepro.com/errors/invalid_client"
}

Rate Limiting

Token-Anfragen sind auf 10 Anfragen pro Minute pro Client begrenzt. Überschreitungen resultieren in einem 429 Too Many Requests Fehler.

Best Practice: Token Caching

Cachen Sie Access Tokens und verwenden Sie sie für mehrere API-Anfragen. Fordern Sie einen neuen Token nur an, wenn der aktuelle abgelaufen ist (alle 60 Minuten).