The Penaxtra public API uses bearer-token authentication scoped per workspace. Tokens are minted in the console, sealed-box encrypted at rest, and shown in cleartext exactly once at creation.
Mint a token
Console → Settings → API tokens → New token. Choose:
- Name - operator-readable label
- Scopes - one or more (see below)
- Expiry - recommended 90 days for production tokens
- IP allowlist (optional) - restrict the token to a CIDR range
The cleartext value is shown once. Capture it in a secret store before navigating away.
Authenticated request
curl -sS https://penaxtra.com/api/v2/endpoints \
-H "Authorization: Bearer $TOKEN"Available scopes
| Scope | Allows |
|---|---|
endpoints:read | List endpoints |
endpoints:write | Create, update, delete endpoints |
scans:read | List scans and read one scan |
scans:write | Start a scan |
suites:read | List saved scan suites |
findings:read | List findings and read one finding |
findings:write | Update finding status (triage, fix, accept risk, mark false positive) |
reports:read | List reports, poll status, download the document |
reports:write | Queue a report for generation |
audit:read | Read the tenant audit log |
cloud_posture:read | List cloud-posture runs |
cloud_posture:write | Start a cloud-posture run |
rag:read | List RAG security runs |
rag:write | Start a RAG security run |
modelscan:read | List model-scan runs |
gateway:read | Read gateway events, agents and policy |
agents:read | List agents |
assets:read | Read the AI asset inventory and the assembled AI-BOM |
threats:read | List correlated threats |
compliance:read | Read framework coverage |
posture:read | Read the posture summary |
Pick the narrowest set the job needs. A CI job that starts a scan and reads the result needs scans:write and findings:read and nothing else.
Read and write are separate scopes on the same resource for a reason. Reading a report is cheap; generating one renders a document in a worker and can span the whole scan history. A dashboard that polls report status should hold reports:read only, so a leaked dashboard token cannot be used to queue work. The same split applies to scans, endpoints, findings, cloud posture and RAG.
Error semantics
| Code | Meaning |
|---|---|
401 missing_token | No Authorization header |
401 invalid_token | Token does not exist or is revoked |
401 expired_token | Token expiry has passed |
403 missing_scope | Token lacks the required scope for the endpoint |
403 ip_not_allowed | Caller IP is outside the token's allowlist |
Rotation
Tokens are rotatable from the console. The rotation flow:
- Mint the new token with the same scopes.
- Deploy the new token to consumers.
- Verify traffic on the new token via the audit log.
- Revoke the old token from Settings → API tokens.
Security notes
- Tokens are stored as a SHA-256 hash; the cleartext is unrecoverable after creation.
- Every request is rate-limited per token (see API rate limits).
- Token usage is audit-logged with the token's short id (first eight chars of the SHA-256), the request path, and a 200/4xx/5xx outcome.
Related
Last reviewed: 2026-08-04. Reviewed by: Engineering. Content type: Developer documentation. Reach the maintainers: [email protected] .