API documentation

Authentication and abilities

• Base address: https://<your-domain>/api/v1
• Send the token as Authorization: Bearer <token>. The token is shown once, when it is created.
• A token belongs to a service account, a non-personal user that can never sign in. It is created by a super admin under Settings > API.
• Each token has abilities, an expiry date (at most 12 months ahead; a token without an expiry is refused) and can be limited to IP addresses or CIDR ranges.
• Every request, including refused ones, is logged in the audit log (method, path without query string, status and address).

Abilities

read:risks, read:assets, read:controls, read:vendors, read:audit, read:kri, read:evidence, write:evidence

Rate limits and pagination

• Hourly limit per token, 600 requests by default. When it is used up the API answers 429 with a Retry-After header.
• Lists use cursor pagination ordered by updated_at, then id. Use per_page (1 to 200, default 50) and follow links.next, or pass meta.next_cursor as cursor, until it is null.
• filter[updated_after] returns rows updated at or after that time, for incremental sync.

Error format

Errors always have this form:

{ "success": false, "error": { "code": "validation_failed", "message": "...", "details": { "field": ["..."] } } }

• 401 Missing, unknown or expired token.
• 403 Missing ability, not a service account's token, or address not allowed.
• 422 Validation failed. error.details maps fields to messages.
• 429 The hourly limit is used up.