Authentication

The TechWatchAlert API uses organization-level API keys as Bearer tokens. No session or cookie is required — a single key is enough for all requests. A key grants read access to the projects and data of its organization.

Prerequisites

API access is restricted to the organization’s PRO plan. If the organization’s plan does not include API access, /v1/ endpoints return a 403 error. Creating keys requires the admin role in the organization.

Creating an API Key

1. Log in to app.techwatchalert.com
2. Open the Organization settings
3. Go to the API tab
4. Click + New key and give it a descriptive name (e.g. CI GitHub, SIEM Splunk)
5. Copy the displayed key — it will only be shown once

Keys have the format twa_ followed by 43 alphanumeric characters (~256 bits of entropy).

Caution

Store your key in a secrets manager (Vault, AWS Secrets Manager, GitHub Secrets…). It cannot be retrieved after closing the creation window.

Restricting a key (expiration & scopes)

On creation, a key can be restricted — least-privilege principle:

• Expiration: an optional expiry date. Past it, the key is rejected (401).
• Scopes: limit the key to certain resource families (e.g. cves, alerts). A call outside its scopes returns 403. A key without a restriction reads everything and writes nothing. Read scopes: org, projects, stack, alerts, eol, urls, cases, workflows, stats, cves, articles, eol-catalog, stats-global. Two write scopes are ticked separately and are never included in an unrestricted key: scans (upload a scanner report) and workflows-write (create, update, enable or delete a workflow).
• Projects: limit the key to specific projects of the organization. Other projects return 404.

Using the Key

Add the Authorization header to every request:

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

Examples

curl

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

Python (httpx)

import httpx

API_KEY = "twa_your_key_here"
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 .

Revoking a Key

From Organization settings → API, click the delete icon next to the key. Revocation is immediate — any request using that key will receive a 401 error.

Limits

• Maximum 10 active keys per organization
• The last_used_at timestamp is updated on every call (visible in the API tab)

Authentication Errors

Code	Detail	Likely cause
401	Clé API manquante ou invalide	Authorization header missing or does not start with twa_
401	Clé API invalide ou révoquée	Unknown or disabled key
401	Clé API expirée	The key’s expiry date has passed
401	Organisation introuvable	The key’s organization no longer exists
403	Cette clé API n'a pas le droit d'accéder à cette ressource.	The route’s scope is not on the key
403	Cette clé API n'a pas le droit d'écrire ici (scope « scans » à accorder explicitement).	Report upload without the scans scope
403	Cette clé API n'a pas le droit d'écrire ici (scope « workflows-write » à accorder explicitement).	Workflow write without the workflows-write scope
403	Accès API non inclus dans l'abonnement de l'organisation	The organization’s plan does not include API access
429	Limite d'appels API dépassée	The plan’s call quota is exhausted