fibuio API-Referenz

Authentication

fibuio nutzt JWT Access-Tokens (15 Min TTL) + Refresh-Tokens (30 Tage). Tokens werden via POST /api/v1/auth/login ausgegeben und in HTTP-only Cookies gespeichert.

Login-Flow

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "demo@fibuio.de",
  "password": "DeinPasswort2026!"
}

→ 200 OK
Set-Cookie: fibuio.at=<JWT>; HttpOnly; Secure; SameSite=Lax
Set-Cookie: fibuio.rt=<refresh>; HttpOnly; Secure; SameSite=Lax

{
  "accessToken": "eyJ...",
  "user": { "id": "...", "email": "...", "displayName": "..." },
  "activeTenantId": "00000000-0000-0000-0000-000000000001"
}

JWT-Payload

{
  "sub": "user-uuid",
  "email": "demo@fibuio.de",
  "tenantId": "tenant-uuid",
  "type": "access",
  "roles": ["Admin"],
  "iat": 1777040280,
  "exp": 1777041180
}

Header-Authentication

Alternativ zu Cookies kann der Bearer-Header genutzt werden — z.B. für Server-zu-Server-Calls:

GET /api/v1/customers
Authorization: Bearer eyJ...

Rate-Limits

Pro Endpoint-Klasse + Tenant-/IP-/User-Schlüssel. Bei Limit: HTTP 429 mit Retry-After-Header.

Response-Header

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1777041240
Retry-After: 12  (nur bei 429)

Code-Beispiele

cURL — Liste Kunden

# 1. Login
curl -sX POST https://next.fibuio.de/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@fibuio.de","password":"..."}' \
  -c cookies.txt

# 2. Use cookie für protected request
curl -s https://next.fibuio.de/api/v1/customers \
  -b cookies.txt

JavaScript / Node 20+

// Login + Token-Caching
const loginRes = await fetch('https://next.fibuio.de/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
});
const { accessToken } = await loginRes.json();

// Authenticated request
const customers = await fetch('https://next.fibuio.de/api/v1/customers', {
  headers: { Authorization: `Bearer ${accessToken}` },
}).then((r) => r.json());

console.log(customers);

Python 3.10+

import httpx

with httpx.Client(base_url='https://next.fibuio.de/api/v1') as cli:
    # Login
    r = cli.post('/auth/login', json={'email': 'demo@fibuio.de', 'password': '...'})
    r.raise_for_status()
    token = r.json()['accessToken']

    # Liste Kunden
    cli.headers['Authorization'] = f'Bearer {token}'
    customers = cli.get('/customers').json()
    print(f'{len(customers)} Kunden')

Webhook-Verifikation

Outbound-Webhooks (z.B. invoice.paid) werden HMAC-SHA256-signiert. Der Empfänger prüft:

// Node-Verify
import crypto from 'node:crypto';
const expected = crypto
  .createHmac('sha256', process.env.FIBUIO_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
const received = req.headers['x-fibuio-signature-256']?.replace('sha256=', '');
if (expected !== received) return res.status(401).end();

Endpoint-Bereiche

Interaktiver Playground

Swagger-UI lädt die OpenAPI-Spec live. Login-Cookie wird automatisch genutzt für „Try it out".