# hightrusted Developer Portal

Gemeinsame Konventionen für alle hightrusted-APIs. Wer einen Endpoint von einem
Modul nutzt, soll alle anderen Module ohne erneute Einarbeitung nutzen können.

Hier dokumentieren wir, was **plattformweit** gilt — die produktspezifischen
Endpoints stehen jeweils in der OpenAPI-Spec des Produkts (z.B.
[`hightrusted-capture/openapi`](https://git.hightrusted.net/hightrusted-capture/openapi)).

## Inhalt (geplant)

- **`auth/`** — API-Key-Schema, OIDC-Anbindung, Sessions, Rotation, Widerruf
- **`errors/`** — Einheitliche Fehler-Codes, HTTP-Status, `request_id`-Konzept
- **`pagination/`** — Cursor-basierte Pagination, Limits, Sortierung
- **`rate-limits/`** — `Retry-After`-Header, 429-Handling, Burst-Verhalten
- **`webhooks/`** — Signatur-Verifikation, Retry-Policy, Idempotenz
- **`ids/`** — Präfix-Schema (`cap_`, `sig_`, `usr_`, …), Format, Generierung
- **`versioning/`** — Major-Versionen im Pfad, Breaking-Change-Policy, Deprecation
- **`status/`** — Status-Page-Konventionen, Maintenance-Windows
- **`sdk-conventions/`** — Was Klienten implementieren müssen (Retries, Timeouts, Logging)

## Authentifizierung — Kurzfassung

Alle hightrusted-APIs nutzen **Bearer-Token** mit API-Keys. Keys werden im jeweiligen
Produkt-Dashboard erzeugt und sind produkt-scoped, d.h. ein CAPTURE-Key funktioniert
nicht für SIGN.

```http
GET /api/v1/...
Authorization: Bearer ht_live_abc123...
```

API-Key-Präfixe:

- `ht_live_…` — Produktions-Key
- `ht_test_…` — Sandbox-Key (kostenlos, ohne echte Wirkung)

## Fehler-Format — Kurzfassung

Einheitlich über alle APIs:

```json
{
  "error": "invalid_argument",
  "message": "URL is required",
  "request_id": "req_01H...",
  "documentation_url": "https://...errors#invalid_argument"
}
```

Jede Antwort hat einen `X-Request-ID`-Header, den du beim Support angeben solltest.

## Rate Limits — Kurzfassung

Limits werden pro API-Key gemessen. Bei Überschreitung:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

Konkrete Limits stehen in der jeweiligen Produkt-Doku.

## Status der Plattform

- **Live-Status:** https://status.hightrusted.net
- **Inzident-History:** https://status.hightrusted.net/history
- **Maintenance-Ankündigungen:** RSS-Feed auf der Status-Page

## Verwandte Repositorys

- [`platform`](https://git.hightrusted.net/hightrusted/platform) — Plattform-Übersicht, Architektur, Produkt-Liste
- [`compliance`](https://git.hightrusted.net/hightrusted/compliance) — DSGVO, AGB-Templates, Whitepaper

## Kontakt

- **Developer-Support:** developers@hightrusted.net
- **Sicherheit:** security@hightrusted.net

## Lizenz

MIT — siehe [LICENSE](./LICENSE). Konventionen dürfen frei nachgenutzt werden.

---

**hightrusted GmbH** — *The European Trust Infrastructure.*
Made in Germany. DSGVO-nativ. eIDAS-konform.