Authentication#

API Keys#

HashWatch uses API keys for authentication on all private endpoints. An API key looks like this:

<team-id>.<secret>

For example: acme-ir.sk_live_a1b2c3d4e5f6...

Sending your API key#

Include your key in the X-API-Key header on every request:

curl https://api.hashwatch.us/api/v1/intel/stats \
  -H "X-API-Key: acme-ir.sk_live_a1b2c3d4e5f6..."

API keys are never logged or stored in plaintext - only a secure HMAC hash is kept on the server. Keep your key confidential; it cannot be recovered if lost (request a new one from your administrator).

Web console sign-in#

You do not have to use the API directly. The same key signs you in to the HashWatch web console at:

https://hashwatch.us/login

(There is also a Sign in link in the top-right of the public dashboard.) Any valid key works - what you can do once inside depends on your role:

• Account Administrators can issue, update, and revoke API keys for their own team, and grant additional or time-limited roles.
• Analyst / Responder / Auditor roles can view the dashboard and manage their own sign-in security (passkey, TOTP, recovery codes) on the Account page.

After your first sign-in with the key, enroll a passkey or authenticator (TOTP) so you can sign in without pasting the key each time. The navigation bar shows only the sections your role can use.

Multi-factor authentication is required in the web console. On first sign-in you are taken to the Account page and must enroll a passkey or authenticator before using anything else.

• API-key sessions (a raw <team>.<secret> key, used by scripts and SIEM integrations) are unaffected - MFA is a console convenience there and programmatic access keeps working without it.
• Invited-user logins (you redeemed a one-time invite code instead of pasting a key) must have MFA enrolled to do anything beyond enrolling it: the requirement is enforced at the API too, so an unenrolled user session is rejected with 403 MFA_REQUIRED on intel and admin routes (only the MFA-enrollment and account-switch endpoints stay reachable). You cannot skip it by calling the API directly.

Reissue your key when you’re done with it. Once you’ve signed in and set up MFA, the Account page can reissue your API key (the old one is revoked immediately and a new one is shown once) - useful if you only needed the key to sign in or are concerned about keeping a copy.

JWT Tokens (optional)#

For high-throughput use cases, you can exchange your API key for a short-lived JWT token (15-minute TTL) and use that for subsequent requests. This avoids the HMAC verification overhead on every call.

Obtain a token#

curl -X POST https://api.hashwatch.us/api/v1/auth/token \
  -H "X-API-Key: acme-ir.sk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

Response:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

expires_in is the token lifetime in seconds (900 = 15 minutes). The signed JWT carries these claims: sub (your team), role (your primary role), roles (your full effective role set - the primary role plus any additional or time-limited grants), and tier. Permissions are the union across every role in roles.

Use the token#

curl https://api.hashwatch.us/api/v1/intel/stats \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Refresh before expiry#

curl -X POST https://api.hashwatch.us/api/v1/auth/refresh \
  -H "Authorization: Bearer <current-token>"

The public key used to verify JWT signatures is available at:

GET https://api.hashwatch.us/.well-known/jwks.json

Roles and Tiers#

Every API key has an assigned role (what actions are allowed) and tier (billing gate for paid features). Both must be satisfied for a request to succeed.

What you can do with an API key#

An API key authenticates you to the private API and carries your role + tier. Depending on those, a key lets you:

• Look up file hashes against the BinTrust corpus of known-good vendor releases and NSRL (intel:lookup).
• View platform statistics (intel:stats).
• Query historical hashes - what the official hash for a piece of software was on any past date (intel:history, basic).
• Pull the download audit trail - provenance proof that vendor files were verified and never stored (intel:downloads, teams).
• Consume the RevokeRadar feed - certificates that signed tracked software and have since been revoked by the CA, plus a queryable revocation history / timeline showing when each cert was revoked (intel:revocations, teams).
• Administer access - issue, update, and revoke keys, with the scope determined by your administrative role (see Administrative roles below).

You can also exchange a key for a short-lived JWT (see JWT Tokens). Keys are HMAC-hashed at rest and shown only once at creation.

Permissions#

Customer (account) roles#

There are three customer roles, assignable only within your own account - never across accounts or over the platform. The internal role key is shown below alongside its default display label (deployments can rename labels for white-labeling, so what you see in your console may differ):

Tier gates (the role must grant the permission and the account’s tier must meet the floor): intel:history requires basic tier; intel:downloads and the RevokeRadar intel:revocations (feed, history timeline, and per-cert detail) require teams tier (formerly paid, renamed 2026-06-17; paid still accepted as a deprecated alias). The earlier responder and senior responder roles were removed (they duplicated analyst/auditor).

account_admin is account-scoped. It can issue, update, and revoke API keys only inside its own account, and may add members or issue keys only with the analyst/auditor roles. It can never see or affect other accounts, change platform settings, grant a platform role, or create another account_admin - promoting someone to Account Admin requires HashWatch staff.

Administrative roles (HashWatch only)#

Platform roles maintain the HashWatch product itself and are never assignable to a customer tenant, regardless of subscription.

The permission sets of all administrative roles (including client_liaison) are fixed by the platform and cannot be edited in the RBAC editor - so no administrator can strip another’s access or lock out the owner.

Multiple roles and time-limited grants#

A key has one primary role (its identity and tier gate) and may also carry additional roles granted on top of it. Each additional grant can be permanent or time-limited (auto-expiring, capped at 30 days) - useful for demos and short-lived elevation during training.

• A key’s effective permissions are the union of its primary role and every currently-active grant. Expired grants simply stop counting; no cleanup is needed.
• The JWT roles claim lists the full effective set; role remains the primary.
• Granting a role still respects authority: platform roles remain owner-only, and a caller can only grant roles at or below its own rank.

Managed via POST /api/v1/admin/keys/{keyID}/roles (grant) and DELETE /api/v1/admin/keys/{keyID}/roles/{role} (revoke).

Tenant impersonation (view-as / manage-as)#

Staff holding tenant:impersonate (client_liaison, platform_admin, platform_owner) can step into a customer context, in one of two scopes:

# Tenant scope: step into a tenant as a generic account_admin.
curl -X POST https://api.hashwatch.us/api/v1/admin/impersonate \
  -H "Authorization: Bearer <staff-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"team_id": "acme-ir", "mode": "manage"}'

# User scope: step into a specific user, assuming THEIR membership role.
curl -X POST https://api.hashwatch.us/api/v1/admin/impersonate \
  -H "Authorization: Bearer <staff-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "<uuid>", "account_id": "<uuid>", "mode": "view"}'

Modes: view (read-only - every write method is rejected with 403) or manage (read-write). Response is a short-lived (30-minute) JWT carrying act (the staffer, recorded as the audit actor) and imp_mode claims.

• Tenant scope mints the session as account_admin on that tenant.
• User scope (provide user_id; account_id only needed if the user belongs to more than one account) assumes the user’s actual membership role in that account
  • so “manage as” an Analyst is limited to what that Analyst can do - and records the impersonated user in an imp_uid claim. Staff users and suspended accounts are rejected.

The assumed role is always a tenant/customer role, so the session has no platform reach and impersonation cannot be chained. Impersonation sessions cannot mint or refresh tokens (no escalation), and every action taken under one is attributed to the staffer in the audit log. Impersonating your own team, an unknown tenant/user, or a target that holds platform roles is rejected.

Tiers#

Error responses#

All errors return JSON with an error field:

{"error": "unauthorized"}
{"error": "forbidden"}
{"error": "rate limit exceeded"}

Rate limits#

Rate limits are enforced at the Cloudflare edge before requests reach the application. Exceeding the limit returns HTTP 429. The Retry-After header (seconds) indicates when you may retry.

Admin authentication endpoints#

These endpoints are used by the Admin Panel web UI and by automation that manages admin sessions. They are separate from the team API key flow above - they authenticate platform administrators, not data consumers.

Token endpoints (current)#

See JWT Tokens above for request/response details.

Passkey (WebAuthn) endpoints#

Passkeys use the Web Authentication API (WebAuthn). Registration and authentication each require two calls: one to get a challenge from the server, and one to return the signed response from the browser/device.

Register a new passkey#

POST /api/v1/admin/mfa/passkey/begin

Auth required: valid admin JWT or API key
Request body: {"display_name": "MacBook Touch ID"}
Response: WebAuthn PublicKeyCredentialCreationOptions challenge object (pass to navigator.credentials.create())

POST /api/v1/admin/mfa/passkey/complete

Auth required: same session as begin
Request body: the PublicKeyCredential object returned by the browser
Response: {"passkey_id": "...", "display_name": "MacBook Touch ID", "created_at": "..."}

Sign in with a passkey#

POST /api/v1/admin/auth/passkey/begin

Auth required: none
Request body: {} (or {"user_handle": "..."} to hint a specific account)
Response: WebAuthn PublicKeyCredentialRequestOptions challenge (pass to navigator.credentials.get())

POST /api/v1/admin/auth/passkey/complete

Auth required: none
Request body: the PublicKeyCredential assertion returned by the browser
Response: {"token": "eyJ...", "expires_at": "..."} - same JWT format as POST /api/v1/auth/token

List and remove passkeys#

GET    /api/v1/admin/mfa/passkeys           # list registered passkeys for the caller
DELETE /api/v1/admin/mfa/passkeys/{id}      # remove a passkey by ID

Both require a valid admin JWT. The caller’s overall MFA status is available at GET /api/v1/admin/mfa/status.

TOTP endpoints#

Enroll TOTP#

POST /api/v1/admin/mfa/totp/enroll

Auth required: valid admin JWT
Request body: {}
Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/HashWatch%3Aplatform-admin?secret=JBSWY3D...&issuer=HashWatch",
  "qr_code_svg": "<svg>...</svg>"
}

The otpauth_url can be scanned as a QR code or entered manually into any authenticator app.

Confirm TOTP enrollment#

After scanning the QR code, verify the first code to activate TOTP:

POST /api/v1/admin/mfa/totp/verify

Auth required: valid admin JWT
Request body: {"code": "123456"}
Response: {"enrolled": true} - TOTP is now active for this account

Disable TOTP#

DELETE /api/v1/admin/mfa/totp

Auth required: valid admin JWT
Request body: {"code": "123456"} - must provide a valid current code to confirm
Response: {"disabled": true}

Recovery code endpoints#

Generate recovery codes#

POST /api/v1/admin/mfa/recovery/generate

Auth required: valid admin JWT
Request body: {}
Response:

{
  "codes": [
    "a3b7-f2d9-1e4c",
    "9x2k-0m5p-7h3q",
    "..."
  ],
  "count": 10,
  "warning": "Store these offline. Each code can only be used once."
}

Calling this endpoint invalidates any previously generated codes for the account.

Sign in with a recovery code#

POST /api/v1/admin/auth/recovery

Auth required: none
Request body: {"code": "a3b7-f2d9-1e4c"}
Response: {"token": "eyJ...", "expires_at": "..."} - the used code is invalidated immediately

Sign-in with TOTP uses POST /api/v1/admin/auth/totp with {"code": "123456"}, returning the same {"token", "expires_at"} shape.

Remaining code count is returned in the X-Recovery-Codes-Remaining response header so the admin panel can warn when codes are running low.