Authentification

L’API TechWatchAlert utilise des clés API au niveau organisation, au format Bearer token. Aucune session ni cookie n’est nécessaire — une seule clé suffit pour toutes les requêtes. Une clé donne accès en lecture aux projets et données de son organisation.

Prérequis

L’accès API est réservé au plan PRO de l’organisation. Si le plan de l’organisation n’inclut pas l’accès API, les endpoints /v1/ retournent une erreur 403. La création de clés requiert le rôle admin dans l’organisation.

Créer une clé API

Connectez-vous à app.techwatchalert.com
Ouvrez les Réglages de l’organisation
Allez dans l’onglet API
Cliquez sur + Nouvelle clé et donnez-lui un nom descriptif (ex : CI GitHub, SIEM Splunk)
Copiez la clé affichée — elle ne sera montrée qu’une seule fois

Les clés ont le format twa_ suivi de 43 caractères alphanumériques (~256 bits d’entropie).

Limiter une clé (expiration & scopes)

À la création, une clé peut être restreinte — principe du moindre privilège :

Expiration : une date d’expiration optionnelle. Au-delà, la clé est refusée (401 Clé API expirée).
Scopes : limitez la clé à certaines familles de ressources (ex. cves, alerts). Un appel hors scope renvoie 403. Une clé sans restriction lit tout et n’écrit rien. Scopes de lecture : org, projects, stack, alerts, eol, urls, cases, workflows, stats, cves, articles, eol-catalog, stats-global. Deux scopes d’écriture se cochent à part et ne sont jamais inclus dans une clé sans restriction : scans (déposer un rapport de scanner) et workflows-write (créer, modifier, activer ou supprimer un workflow).
Projets : limitez la clé à des projets précis de l’organisation. Les autres projets renvoient 404.

Utiliser la clé

Ajoutez l’en-tête Authorization à chaque requête :

GET /api/v1/me HTTP/1.1
Host: app.techwatchalert.com
Authorization: Bearer twa_votre_cle_ici

Exemples

curl

curl -H "Authorization: Bearer twa_votre_cle_ici" \
  https://app.techwatchalert.com/api/v1/me

Python (httpx)

import httpx

API_KEY = "twa_votre_cle_ici"
BASE_URL = "https://app.techwatchalert.com/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}

with httpx.Client(headers=headers) as client:
    me = client.get(f"{BASE_URL}/me").json()
    print(me)

JavaScript (fetch)

const API_KEY = process.env.TWA_API_KEY;
const BASE_URL = 'https://app.techwatchalert.com/api/v1';

const res = await fetch(`${BASE_URL}/me`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await res.json();

GitHub Actions

- name: Check CVE alerts
  env:
    TWA_API_KEY: ${{ secrets.TWA_API_KEY }}
  run: |
    curl -sf \
      -H "Authorization: Bearer $TWA_API_KEY" \
      "https://app.techwatchalert.com/api/v1/organizations" | jq .

Révoquer une clé

Depuis Réglages de l’organisation → API, cliquez sur l’icône de suppression à côté de la clé. La révocation est immédiate — toute requête utilisant cette clé recevra une erreur 401.

Limites

Maximum 10 clés actives par organisation
La mise à jour de last_used_at est tracée à chaque appel (visible dans l’onglet API)

Erreurs d’authentification

Code	Détail	Cause probable
`401`	`Clé API manquante ou invalide`	En-tête `Authorization` absent ou ne commence pas par `twa_`
`401`	`Clé API invalide ou révoquée`	Clé inconnue ou désactivée
`401`	`Clé API expirée`	La date d’expiration de la clé est passée
`401`	`Organisation introuvable`	L’organisation de la clé n’existe plus
`403`	`Cette clé API n'a pas le droit d'accéder à cette ressource.`	Le scope de la route ne figure pas sur la clé
`403`	`Cette clé API n'a pas le droit d'écrire ici (scope « scans » à accorder explicitement).`	Dépôt d’un rapport sans le scope `scans`
`403`	`Cette clé API n'a pas le droit d'écrire ici (scope « workflows-write » à accorder explicitement).`	Écriture d’un workflow sans le scope `workflows-write`
`403`	`Accès API non inclus dans l'abonnement de l'organisation`	Plan de l’org sans accès API
`429`	`Limite d'appels API dépassée`	Quota d’appels de l’offre atteint