Přeskočit obsah

API — Začínáme

Autentizace, základní URL, verzování a limity požadavků

Verze dokumentu: 1.1.0
Poslední aktualizace: 2026-04-04

1. Základní URL

Všechny endpointy API jsou relativní k vaší instalaci MazeVault:

https://<your-mazevault-host>/api/v1/

Příklad: 

https://vault.example.com/api/v1/health

2. Verzování API

Verze Stav Prefix cesty
v1 Aktuální — Stabilní /api/v1/
v2 Rezervováno (Zero-Knowledge endpointy) /api/v2/

Note

Pro všechny standardní integrace používejte API v1. API v2 je vyhrazeno pro operace s šifrováním typu zero-knowledge a pro běžné případy použití není vyžadováno.

3. Autentizace

Varianta A: Bearer token (interaktivní / session-based)

Získejte token prostřednictvím jednoho z autentizačních endpointů a poté jej přidejte do všech následujících požadavků:

GET /api/v1/secrets HTTP/1.1
Host: vault.example.com
Authorization: Bearer ***REMOVED***

Získání tokenu — Lokální autentizace (SRP)

Krok 1: Inicializace 

POST /api/v1/auth/srp/init HTTP/1.1
Content-Type: application/json

{
  "username": "john.doe"
}

Odpověď: 

{
  "salt": "base64-encoded-salt",
  "server_public_key": "base64-encoded-B"
}

Krok 2: Ověření 

POST /api/v1/auth/srp/verify HTTP/1.1
Content-Type: application/json

{
  "username": "john.doe",
  "client_public_key": "base64-encoded-A",
  "client_proof": "base64-encoded-M1"
}

Odpověď: 

{
  "access_token": "***REMOVED***",
  "token_type": "Bearer",
  "expires_in": 86400,
  "server_proof": "base64-encoded-M2"
}

Získání tokenu — OAuth 2.0 Client Credentials

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<id>&client_secret=<secret>

Note

Endpoint pro OAuth 2.0 token je na /oauth/token (ne pod /api/v1/).

Odpověď: 

{
  "access_token": "***REMOVED***",
  "token_type": "Bearer",
  "expires_in": 86400
}

Získání tokenu — Univerzální autentizace (API klíč)

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

{
  "client_id": "<your-client-id>",
  "client_secret": "<your-client-secret>"
}

Odpověď: 

{
  "access_token": "***REMOVED***",
  "token_type": "Bearer",
  "expires_in": 86400
}

Varianta B: API token (programový přístup)

Vytvořte API token ve webovém rozhraní MazeVault (Uživatelské nastavení → API tokeny) a poté jej použijte přímo:

GET /api/v1/secrets HTTP/1.1
Host: vault.example.com
Authorization: Bearer mvt_abc123def456...

4. Limity požadavků

Kategorie endpointu Limit Okno Hlavička
Autentizace 10 1 minuta X-RateLimit-Limit
API (autentizované) 100 1 minuta X-RateLimit-Limit
OCSP 1000 1 minuta —
Health Neomezeno — —

Hlavičky limitu požadavků jsou součástí každé odpovědi:

Hlavička Popis
X-RateLimit-Limit Maximální počet požadavků za okno
X-RateLimit-Remaining Zbývající požadavky v aktuálním okně
X-RateLimit-Reset Unix timestamp resetování okna

Při překročení limitu API vrátí 429 Too Many Requests.

5. Chybové odpovědi

Všechny chyby mají jednotný JSON formát:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Secret name is required",
    "details": [
      {
        "field": "name",
        "message": "This field is required"
      }
    ],
    "request_id": "req_abc123"
  }
}

HTTP stavové kódy

Kód Význam Typická příčina
200 OK Úspěšný GET, PUT
201 Created Úspěšný POST (zdroj vytvořen)
204 No Content Úspěšný DELETE
400 Bad Request Chyba validace, chybný formát požadavku
401 Unauthorized Chybějící nebo expirovaný token
403 Forbidden Nedostatečná oprávnění
404 Not Found Zdroj neexistuje
409 Conflict Duplicitní zdroj, konflikt verzí
429 Too Many Requests Překročen limit požadavků
500 Internal Server Error Neočekávaná chyba serveru

Běžné chybové kódy

Chybový kód Popis
AUTH_REQUIRED Nebyl poskytnut autentizační token
AUTH_EXPIRED Platnost tokenu vypršela — proveďte opětovnou autentizaci
AUTH_INVALID Token je neplatný nebo chybně formátován
PERMISSION_DENIED Uživatel nemá požadované oprávnění
VALIDATION_ERROR Validace těla požadavku selhala
RESOURCE_NOT_FOUND Požadovaný zdroj neexistuje
RESOURCE_CONFLICT Zdroj již existuje nebo konflikt verzí
RATE_LIMITED Překročen limit požadavků
CSRF_INVALID CSRF token chybí nebo je neplatný
LICENSE_EXPIRED Platnost licence vypršela — kontaktujte podporu

6. Stránkování

Endpointy pro výpis seznamů podporují stránkování:

GET /api/v1/secrets?page=1&per_page=25 HTTP/1.1

Hlavičky odpovědi:

Hlavička Popis
X-Total-Count Celkový počet zdrojů
X-Page Číslo aktuální stránky
X-Per-Page Počet položek na stránku

7. Kontrola stavu

Ověření dostupnosti API:

GET /api/v1/health HTTP/1.1

Odpověď: 

{
  "status": "healthy",
  "version": "1.8.0",
  "components": {
    "database": "healthy",
    "redis": "healthy",
    "ocsp": "healthy"
  }
}

Související