Authentication

Audience

Integrators automating AIR with bearer API keys.

TL;DR

1. Create a domain-scoped API key in the AIR portal — Getting started.
2. Send Authorization: Bearer <rawKey> on every request.
3. Each key works in one domain only — other domains return 404.
4. Request scopes when creating the key, or use integrations:full. Missing scope → 403 with API key missing required scope: ….
5. Poll documents and assessments for async work — Async jobs.

---

Bearer API keys

Authorization: Bearer <rawKey>

Keys are opaque strings (three dot-separated segments). The server trims whitespace after Bearer.

Key lifecycle

Step	Where
Create service account	Portal → domain → API Keys
Mint key	Select scopes; copy rawKey once
Use	Authorization: Bearer <rawKey> on every request
Rotate	Create new key, deploy, revoke old key in portal
Revoke	Revoked keys return 401

Keys are bound to the domain where they are created. Use one key per domain.

Domain scoping

Symptom	Likely cause
403 — missing scope	Key lacks that scope
404 on project/assessment routes	Key is for a different domain

Confirm your domain: GET /domains/.

What API keys can access

Area	API key
Domains, projects, assessments, uploads, search	Yes — per scopes
Domain portfolio dashboard	Yes — portfolio:read
Org portfolio dashboard	No — portal users only
API key / service account management	No — portal only
Billing, user profile	No — portal only

Scopes

Format: resource:action (for example, projects:read).

Scope	Grants
projects:read	Documents, artifacts, sources; slug lookup
projects:write	Upload, archive, delete, regenerate
assessments:read	Assessments, reports, stages
assessments:write	Start, retry, terminate assessments
domains:read	GET /domains/, list domain projects, slug lookups
domains:write	Create projects in the domain
portfolio:read	Domain portfolio dashboard
search:read	POST /search
integrations:full	All integrator scopes above

Rules: at least one scope required; write implies read on the same resource.

Recommended presets

Use these when creating a key in the portal:

Report reader — download completed reports only:

["assessments:read", "projects:read", "domains:read"]

Assessment runner — upload, assess, read reports:

["assessments:read", "assessments:write", "projects:read", "projects:write", "domains:read"]

Full pipeline — create projects, upload, assess, search:

[
  "projects:read",
  "projects:write",
  "assessments:read",
  "assessments:write",
  "domains:read",
  "domains:write",
  "portfolio:read",
  "search:read"
]

All integrator scopes: ["integrations:full"]

---

Portal users

Humans sign in at https://air.thalus.ai to manage projects, review assessments, and create API keys. Automations should use bearer API keys, not browser sessions.

Related

• Getting started — create your first key
• Concepts — domain hierarchy and discovery limits
• Errors — 401, 403, 404 semantics