Introduction
The Verity Prover is a proxy server that enables you to generate cryptographic proofs for API interactions. It acts as a middleware between your application and target APIs, allowing you to prove specific aspects of the request/response cycle while selectively redacting sensitive information.
Key Concepts
Request ID
Every proof generation requires a unique Request ID (UUID) to track and retrieve the proof. You can generate one using:
Proof Subscription
Proofs are delivered asynchronously via Server-Sent Events (SSE). You’ll need to establish a connection to receive proofs as they’re generated.
Core Endpoints
Proxy Endpoint (/proxy
)
This endpoint forwards your requests to target APIs while generating proofs. You can use any HTTP method to call this endpoint, such as GET, POST, PUT, DELETE, etc.
Required Headers:
T-PROXY-URL
: The target API URL you want to callT-REQUEST-ID
: Your generated UUID for tracking the proofT-REDACTED
(optional): Comma-separated list of fields to redactT-PROVE-FAILED-REQ
(optional): If set to true, the proof will be generated even if the request fails
Redaction Syntax:
The T-REDACTED
header allows you to specify which parts of the request and response should be redacted from the generated proofs. Understanding the syntax is crucial for effectively protecting sensitive information while maintaining the integrity of your proofs. Below is a detailed explanation of each redaction pattern you can use:
-
req:body:fieldName
Redact a specific field in the request body.
ReplacefieldName
with the exact name of the field you want to redact.
Example:
req:body:password
This will redact thepassword
field from the request body. -
req:header:headerName
Redact a specific header in the request.
ReplaceheaderName
with the name of the header you wish to redact.
Example:
req:header:Authorization
This will redact theAuthorization
header from the request. -
res:body:fieldName
Redact a specific field in the response body.
ReplacefieldName
with the name of the field you want to redact.
Example:
res:body:creditCardNumber
This will redact thecreditCardNumber
field from the response body. -
res:header:headerName
Redact a specific header in the response.
ReplaceheaderName
with the name of the header you wish to redact.
Example:
res:header:Set-Cookie
This will redact theSet-Cookie
header from the response. -
res:query:queryName
Redact a specific query parameter in the response URL.
ReplacequeryName
with the name of the query parameter you want to redact.
Example:
res:query:userId
This will redact theuserId
query parameter from the response URL. -
res:path:PathIndex
Redact a specific segment of the response URL path based on its position.
ReplacePathIndex
with the numerical position of the path segment you wish to redact, starting from 1.
Example:
res:path:2
If the response URL ishttps://api.example.com/users/12345/profile
,
res:path:2
will redact12345
from the path. -
search:substring
Redact all occurrences of a specific substring within the response.
Replacesubstring
with the exact phrase or word you want to redact.
Example:
search:secret
This will redact every instance of the word “secret” in the response content.
Usage Tips:
-
Combining Multiple Redactions: You can specify multiple redaction patterns by separating them with commas.
Example:
res:body:id,req:header:Authorization,search:password
-
Order Matters: The redactions are applied in the order they are specified. Ensure that more general redactions (like
search
) do not inadvertently redact intended data. -
Testing Redactions: Before deploying, test your redaction patterns to ensure they effectively hide the desired information without affecting other parts of the data.
Proof Subscription (/proof/{requestId}
)
Subscribe to receive proofs for a specific request ID via SSE.
Basic POST Request
Simple GET Request
Subscribing to Proofs
Best Practices
- Always Generate Fresh UUIDs: Use a new UUID for each proof request to avoid collisions.
- Subscribe First: Set up your SSE connection before making the proxy request.
- Handle Timeouts: Implement appropriate timeout handling for both proxy requests and SSE connections.
- Redact Sensitive Data: Use the
T-REDACTED
header to protect sensitive information from TLS proofs while maintaining proof validity. - Error Handling: The API uses standard HTTP status codes:
- 200: Successful request
- 400: Bad request (invalid headers or body)
- 404: Target API not found
- 500: Server error