API REST Scanyze

L'API Scanyze expose 160+ endpoints REST organisés en sections (auth, targets, scans, findings, code, pentest, cloud, dark web, partner, admin). Tous les endpoints sont protégés par JWT ou API key, avec isolation multi-tenant via Row-Level Security PostgreSQL.

URLs de base

Le préfixe est /v1 (pas /api/v1). Tous les endpoints documentés ci-dessous sont préfixés implicitement.

Documentation interactive

Swagger UI disponible :

• Production : https://api.scanyze.com/v1/docs/
• Staging : https://api.scanyze.secuaas.ovh/v1/docs/

Le fichier OpenAPI 3.0 brut est exposé sur /v1/docs/swagger.json et /v1/docs/swagger.yaml. Disponible plan Starter+ (l'API est désactivée pour les plans Free et Essentiel).

Authentification

JWT (utilisateurs interactifs)

1. Login :

   curl -X POST https://api.scanyze.com/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"vous@monentreprise.ca","password":"VotreMotDePasse"}'

   Réponse :

   {
     "access_token": "eyJhbGc...",
     "refresh_token": "eyJhbGc...",
     "expires_in": 3600,
     "token_type": "Bearer"
   }

2. Requêtes authentifiées :

   curl https://api.scanyze.com/v1/targets \
     -H "Authorization: Bearer eyJhbGc..."

3. Refresh du token (à expiration) :

   curl -X POST https://api.scanyze.com/v1/auth/refresh \
     -H "Content-Type: application/json" \
     -d '{"refresh_token":"eyJhbGc..."}'

SSO Zitadel (Enterprise)

GET /v1/auth/sso/zitadel

Redirige vers auth.secuaas.com pour l'authentification OIDC. À l'issue, le frontend reçoit un code d'autorisation qu'il échange contre des tokens JWT via POST /v1/auth/sso/callback.

API Keys (intégrations programmatiques)

Recommandé pour les scripts, CI/CD, intégrations.

1. Créez une clé via /settings/api-docs ou POST /v1/api-keys (frontend ou API).
2. Choisissez les scopes :
   • targets:read / targets:write
   • scans:read / scans:write / scans:launch
   • findings:read / findings:write
   • code:read / code:write / code:scan
   • agents:read / agents:write
   • reports:read
   • admin:* (pour admin endpoints — réservé tenant_admin)
3. Copiez la clé immédiatement (affichée une seule fois). Format : sk_live_xxxxxxxxxxxx.
4. Utilisation :

   curl https://api.scanyze.com/v1/targets \
     -H "X-API-Key: sk_live_xxxxxxxxxxxx"

Les API keys peuvent être révoquées à tout moment via /settings/api-docs → bouton Révoquer.

Rate limiting

Headers de réponse pour suivre votre consommation :

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1714398312

En cas de dépassement : 429 Too Many Requests avec Retry-After en secondes.

Endpoints principaux

Liste non exhaustive — voir Swagger pour la référence complète. Source : secuscan-api/internal/bootstrap/routes.go.

Targets

Scans

Findings

Code

Pentest

Dark Web

Cloud

AI Credits

Notifications (SSE)

GET /v1/notifications/stream
Accept: text/event-stream
Authorization: Bearer eyJhbGc...

Stream Server-Sent Events temps réel : nouveaux scans, findings, breaches, alertes quota, etc.

Admin (réservé tenant_admin)

• /v1/admin/users — gestion des utilisateurs du tenant
• /v1/admin/audit — logs d'audit
• /v1/admin/settings — config tenant

Partner (réservé MSP, voir doc MSP)

• /v1/partner/account
• /v1/partner/tenants
• /v1/partner/dashboard
• /v1/partner/billing
• ...

Exemples complets

Créer une cible et lancer un scan

# 1. Créer la cible
curl -X POST https://api.scanyze.com/v1/targets \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site corporatif",
    "domain": "monentreprise.ca",
    "scanConfig": {
      "scanProfile": "gentle",
      "scanSubdomains": true,
      "portScan": true,
      "sslCheck": true,
      "vulnScan": true,
      "dnsAudit": true,
      "emailSecurity": true,
      "httpHeaders": true
    }
  }'
# Réponse: {"id": "uuid", "status": "active", ...}

# 2. Lancer un scan complet
curl -X POST https://api.scanyze.com/v1/scans \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "targetId": "uuid-de-la-cible"
  }'
# Réponse: {"id": "scan-uuid", "status": "pending", ...}

# 3. Suivre l'avancement (polling)
curl https://api.scanyze.com/v1/scans/scan-uuid \
  -H "X-API-Key: sk_live_xxx"
# Réponse: {"status": "running", "progress": 42, ...}

# 4. Une fois completed, récupérer les findings
curl https://api.scanyze.com/v1/scans/scan-uuid/findings \
  -H "X-API-Key: sk_live_xxx"

# 5. Télécharger le rapport PDF technique
curl https://api.scanyze.com/v1/scans/scan-uuid/report.pdf?type=technical \
  -H "X-API-Key: sk_live_xxx" \
  -o rapport-technique.pdf

Lancer une analyse IA sur un finding

curl -X POST https://api.scanyze.com/v1/findings/finding-uuid/ai-analysis \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"provider": "gpu"}'
# Réponse: {"jobId": "uuid", "status": "pending"}

# Polling jusqu'à completion
curl https://api.scanyze.com/v1/findings/finding-uuid/ai-analysis \
  -H "X-API-Key: sk_live_xxx"
# Réponse: {"status": "completed", "analysis": "...", "creditsConsumed": 1, ...}

Codes d'erreur

Format d'erreur standard :

{
  "error": "validation_error",
  "message": "Field 'domain' must be a valid FQDN",
  "details": {
    "field": "domain",
    "value": "not-valid"
  },
  "request_id": "req_abc123"
}

Le request_id permet de retrouver la trace exacte côté Scanyze (utile pour le support).

Webhooks entrants

Pour les intégrations Git (push events) :

• POST /v1/webhooks/git/github (HMAC-SHA256 dans X-Hub-Signature-256)
• POST /v1/webhooks/git/gitlab (token dans X-Gitlab-Token)
• POST /v1/webhooks/git/bitbucket (UUID dans X-Hook-UUID)
• POST /v1/webhooks/git/forgejo (HMAC dans X-Forgejo-Signature)
• POST /v1/webhooks/git/azure (HMAC dans X-Vss-Subscriptionid)

Le secret est généré dans /settings/integrations → onglet Webhooks Git → bouton Régénérer.

SDK clients

Aucun SDK officiel publié pour l'instant. L'API étant standard REST + OpenAPI, vous pouvez générer un client dans votre langage préféré via :

# Exemple : générer un client Go
openapi-generator-cli generate -i https://api.scanyze.com/v1/docs/swagger.json -g go -o ./scanyze-client-go

# Python
openapi-generator-cli generate -i https://api.scanyze.com/v1/docs/swagger.json -g python -o ./scanyze-client-python

Sources de cette page

• Routes : secuscan-api/internal/bootstrap/routes.go
• Handlers : 183 fichiers dans secuscan-api/internal/api/handlers/
• Swagger : généré via swaggo/swag — annotations dans le code Go

À jour pour Scanyze v0.130.x.