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

1. Connectez-vous à app.techwatchalert.com
2. Ouvrez les Réglages de l’organisation
3. Allez dans l’onglet API
4. Cliquez sur + Nouvelle clé et donnez-lui un nom descriptif (ex : CI GitHub, SIEM Splunk)
5. 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).

Attention

Stockez votre clé dans un gestionnaire de secrets (Vault, AWS Secrets Manager, GitHub Secrets…). Elle ne peut pas être récupérée après la fermeture de la fenêtre de création.

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 a accès à tout. Scopes disponibles : org, projects, stack, alerts, eol, urls, cases, workflows, stats, cves, articles, eol-catalog.
• 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	Propriétaire de l'organisation introuvable	Propriétaire de l’org supprimé ou désactivé
403	Cette clé API n'a pas le droit « … »	La clé est limitée à certains scopes
403	Accès API non inclus dans l'abonnement de l'organisation	Plan de l’org sans accès API — upgrade requis