Idempotency
Use the Idempotency-Key header to retry Scrut API write requests safely without creating duplicate uploads or findings.
Every write request to a /v1 endpoint requires an Idempotency-Key header. The key identifies one logical write, so you can retry a failed or timed-out request without uploading the same files twice or creating duplicate vulnerability findings.
Which Requests Need a Key
Send an Idempotency-Key header with every write request:
POST /v1/evidence/{evidenceId}/attachmentsPOST /v1/vulnerabilitiesPATCH /v1/vulnerabilities/{vulnerabilityId}
Read requests and the token endpoint don't need a key. A write request without the header returns 400 idempotency_key_required.
Key Format
- Keys are 1 to 128 characters long.
- Keys can contain letters, numbers, and the characters
.,_,~, and-. - A UUID works well.
curl -X POST https://api.scrut.io/v1/vulnerabilities \
-H "Authorization: Bearer $SCRUT_ACCESS_TOKEN" \
-H "Idempotency-Key: d1f5a7b2-8c3e-4f60-9a1b-2c3d4e5f6a7b" \
-H "Content-Type: application/json" \
-d '{ "vulnerabilityId": "VUL-5672", "title": "Public S3 bucket", "severity": "high", "status": "open" }'
How Scrut Handles a Repeated Key
| You send | Scrut returns |
|---|---|
| A new key | Processes the write and stores the successful response |
| The same key with the same request body, within 24 hours | The stored successful response, without repeating the write, plus the header Idempotent-Replayed: true |
| The same key with a different request body | 409 idempotency_key_reused |
| The same key while the original request is still processing | 409 idempotency_request_in_progress |
Stored responses are replayed for 24 hours.
Retry a Write Safely
- Generate a new key for each logical write, such as each file upload or each new finding.
- If the request fails with a network error, a timeout, a
429, or a5xxstatus, retry it with the same key and the same body. - If the retry returns
409 idempotency_request_in_progress, wait and retry again with the same key. - When you change the request body, generate a new key.
Pro Tip! Store the key alongside the record your integration is syncing, such as a scanner finding ID. That way, a retry after a crash reuses the original key instead of creating a duplicate.
Contact support@scrut.io for further assistance.