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 + read LLM endpoints |
endpoints:write | Create, update, delete endpoints |
scans:read | List + read scans, findings |
scans:write | Trigger scans, cancel scans |
findings:read | List + read findings |
findings:write | Update finding status (triage, resolve, accept, mark false positive) |
reports:generate | Create reports |
reports:read | List + download reports |
audit:read | Read the tenant audit log |
webhooks:write | Manage webhook targets |
Pick the narrowest set required for the use case; a per-CI-job token typically needs only scans:write + findings:read.
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-06-13. Reviewed by: Engineering. Content type: Developer documentation. Reach the maintainers: [email protected] .