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 the scope returns 403. An unrestricted key has access to everything. Available scopes: org, projects, stack, alerts, eol, urls, cases, workflows, stats, cves, articles, eol-catalog.
• 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	Missing Authorization header or value doesn’t start with twa_
401	Clé API invalide ou révoquée	Unknown or deactivated key
401	Clé API expirée	The key’s expiration date has passed
401	Propriétaire de l'organisation introuvable	Organization owner deleted or deactivated
403	Cette clé API n'a pas le droit « … »	The key is limited to certain scopes
403	Accès API non inclus dans l'abonnement de l'organisation	Organization plan without API access — upgrade required