Skip to content

Authentication

Vex Raptor's REST API under /api/v1 uses two credential types: JWT bearer tokens for interactive/user calls, and org API keys for automation (CI).

Session tokens (JWT)

Interactive clients log in with email + password (or SSO) and receive a JWT.

curl -sS -X POST https://<host>/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "expires_in": 7200
}

Send the token on every subsequent request:

curl -sS https://<host>/api/v1/auth/me \
  -H "Authorization: Bearer <JWT>"

Token characteristics:

Property Value
Algorithm HS256, signed with your SECRET_KEY
Lifetime 2 hours (expires_in: 7200)
Claims sub, role, org_id, jti, iat, exp
Revocation jti is checked against a server-side blocklist on every request

Logout revokes the current token immediately:

curl -sS -X POST https://<host>/api/v1/auth/logout \
  -H "Authorization: Bearer <JWT>"

Store tokens safely

Treat the JWT as a bearer secret. Do not log it, embed it in URLs, or commit it. Prefer short sessions and re-authenticate rather than caching long-lived tokens.

SSO / OIDC

On enterprise plans, users authenticate through your identity provider. The id-token signature is verified against your IdP's JWKS before a session is issued. See SSO & RBAC.

Org API keys (automation)

CI and machine-to-machine calls use a per-org API key sent in X-Vex-Key instead of a JWT.

curl -sS -X POST https://<host>/api/v1/webhook/scan \
  -H "X-Vex-Key: <org-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://staging.example.com","fail_on":"high"}'

API keys are:

  • Scoped to a single org and a defined set of actions.
  • Revocable at any time from the console (revocation is immediate).
  • Rotatable — issue a new key, deploy it, then revoke the old one.

See managing API keys.