Authentifizierung (Authentication)

Jede Anfrage an die Partner-API muss mit HMAC-SHA256-Anfragensignierung authentifiziert werden. Dies stellt sicher, dass Anfragen sowohl authentisch sind als auch während der Übertragung nicht manipuliert wurden.

Erforderliche Header

Signaturerstellung

Die Signatur wird berechnet, indem eine punktgetrennte Nachrichtenzeichenkette erstellt und mit Ihrem API-Schlüssel-Secret signiert wird:

message = "{timestamp}.{nonce}.{method}.{path}.{body}"
signature = HMAC-SHA256(apiKeySecret, message).hexDigest()

Die Nachrichtenkomponenten, verbunden mit Punkten (.):

1. timestamp — Unix-Zeitstempel in Sekunden (gleicher Wert wie im X-Timestamp-Header)
2. nonce — Derselbe Wert, der im X-Nonce-Header gesendet wird
3. method — Die HTTP-Methode in Großbuchstaben (z. B. GET, POST)
4. path — Der vollständige Anfragepfad (z. B. /v2/partners/products/tickets)
5. body — Der rohe JSON-Anfragekörper als String. Bei GET-Anfragen ohne Body verwenden Sie einen leeren String ""

Der resultierende HMAC-Digest muss als Kleinbuchstaben-Hex kodiert werden.

Beispiele

API_KEY="your-api-key"
API_SECRET="your-api-secret"
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')
METHOD="GET"
REQ_PATH="/v2/partners/products/tickets"
BODY=""

MESSAGE="${TIMESTAMP}.${NONCE}.${METHOD}.${REQ_PATH}.${BODY}"

SIGNATURE=$(echo -n "${MESSAGE}" | \
  openssl dgst -sha256 -hmac "${API_SECRET}" | \
  awk '{print $2}')

curl -X GET "https://api.vignetim.com${REQ_PATH}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}"

Wichtige Hinweise

• Der X-Timestamp muss innerhalb von 5 Minuten (300 Sekunden) der Serverzeit liegen. Anfragen mit veralteten Zeitstempeln werden mit einem 401-Fehler abgelehnt.
• Jeder X-Nonce-Wert muss eindeutig sein und darf nur einmal verwendet werden. Die Wiederverwendung eines Nonce führt zu einem 401-Fehler.
• Verwenden Sie immer den rohen, unformatierten JSON-Body-String für die Signaturberechnung. Formatieren oder re-serialisieren Sie den Body nicht vor dem Signieren.
• Die Signatur muss als Kleinbuchstaben-Hex kodiert sein. Verwenden Sie kein Base64.