> ## Documentation Index > Fetch the complete documentation index at: https://core.anylayer.org/llms.txt > Use this file to discover all available pages before exploring further. # Evaluate Policy > Evaluate trust policies against a subject ## Overview Evaluate trust policies to determine if a subject meets specific trust requirements. This endpoint allows you to check compliance with trust-based access control, verify credentials, and assess eligibility for services based on trust scores and attestations. Use this endpoint to implement trust-based access control, verify user credentials, and assess eligibility for services based on trust requirements. ## Parameters Trust policy to evaluate Unique policy identifier Policy name Policy description Policy requirements Requirement type (trustScore, attestation, skill, relationship, etc.) Comparison operator (gte, lte, eq, in, contains, etc.) Requirement value Requirement weight (0-1) Whether requirement is mandatory Policy conditions Condition type (and, or, not) Requirements to evaluate Minimum score threshold (0-100) Policy expiry date (ISO 8601) Subject identity to evaluate (ZKS ID or wallet address) Additional context for evaluation Service requesting evaluation Action being evaluated Additional metadata Evaluation options Include detailed evaluation results (default: true) Include relevant attestations (default: true) Include trust score breakdown (default: true) Use strict evaluation mode (default: false) ## Response Indicates if the evaluation was successful Whether the subject passed the policy evaluation Overall evaluation score (0-100) Policy threshold score Evaluated subject identity Policy details Policy identifier Policy name Policy description Requirement evaluation results Requirement type Whether requirement passed Requirement score Requirement weight Whether requirement is mandatory Requirement evaluation details Relevant attestations used in evaluation Attestation identifier Attestation schema Attestation trust score Relevance to policy (0-1) Score breakdown by category Overall trust score Attestation-based score Skill-based score Relationship-based score Achievement-based score Recommendations for improvement Recommendation type Recommendation description Expected impact on score Recommendation priority (high, medium, low) ISO 8601 timestamp of the evaluation ## Examples ```bash cURL (Basic Policy Evaluation) theme={null} curl -X POST "https://api.onzks.com/v1/trust/evaluate" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "policy": { "id": "defi_access_policy", "name": "DeFi Protocol Access", "description": "Access policy for DeFi protocols", "requirements": [ { "type": "trustScore", "operator": "gte", "value": 70, "weight": 0.4, "required": true }, { "type": "attestation", "operator": "contains", "value": "skill", "weight": 0.3, "required": true }, { "type": "attestation", "operator": "contains", "value": "relationship", "weight": 0.3, "required": false } ], "threshold": 75 }, "subject": "alice.zks", "context": { "service": "defi_protocol", "action": "lending" } }' ``` ```bash cURL (Complex Policy Evaluation) theme={null} curl -X POST "https://api.onzks.com/v1/trust/evaluate" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "policy": { "id": "whale_trader_policy", "name": "Whale Trader Access", "description": "Access policy for high-volume traders", "requirements": [ { "type": "trustScore", "operator": "gte", "value": 85, "weight": 0.5, "required": true }, { "type": "attestation", "operator": "contains", "value": "achievement", "weight": 0.3, "required": true }, { "type": "attestation", "operator": "contains", "value": "reputation", "weight": 0.2, "required": false } ], "conditions": [ { "type": "and", "requirements": [0, 1] } ], "threshold": 80 }, "subject": "bob.zks", "options": { "includeDetails": true, "includeAttestations": true, "includeScore": true, "strictMode": false } }' ``` ```javascript JavaScript theme={null} async function evaluatePolicy(policy, subject, context = {}, options = {}) { const { includeDetails = true, includeAttestations = true, includeScore = true, strictMode = false } = options; const requestBody = { policy, subject, context, options: { includeDetails, includeAttestations, includeScore, strictMode } }; const response = await fetch('https://api.onzks.com/v1/trust/evaluate', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify(requestBody) }); const result = await response.json(); console.log(`Policy Evaluation for ${subject}:`); console.log(`Passed: ${result.passed}`); console.log(`Score: ${result.score}/${result.threshold}`); console.log(`Requirements passed: ${result.requirements.filter(r => r.passed).length}/${result.requirements.length}`); if (result.recommendations && result.recommendations.length > 0) { console.log('Recommendations:'); result.recommendations.forEach(rec => { console.log(`- ${rec.description} (${rec.priority} priority)`); }); } return result; } // Usage examples const defiPolicy = { id: 'defi_access_policy', name: 'DeFi Protocol Access', description: 'Access policy for DeFi protocols', requirements: [ { type: 'trustScore', operator: 'gte', value: 70, weight: 0.4, required: true }, { type: 'attestation', operator: 'contains', value: 'skill', weight: 0.3, required: true } ], threshold: 75 }; await evaluatePolicy(defiPolicy, 'alice.zks', { service: 'defi_protocol', action: 'lending' }); ``` ```python Python theme={null} import requests import json def evaluate_policy(policy, subject, context=None, options=None): if context is None: context = {} if options is None: options = {} request_body = { 'policy': policy, 'subject': subject, 'context': context, 'options': { 'includeDetails': options.get('includeDetails', True), 'includeAttestations': options.get('includeAttestations', True), 'includeScore': options.get('includeScore', True), 'strictMode': options.get('strictMode', False) } } response = requests.post( 'https://api.onzks.com/v1/trust/evaluate', headers={ 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, json=request_body ) result = response.json() print(f"Policy Evaluation for {subject}:") print(f"Passed: {result['passed']}") print(f"Score: {result['score']}/{result['threshold']}") print(f"Requirements passed: {len([r for r in result['requirements'] if r['passed']])}/{len(result['requirements'])}") if result.get('recommendations'): print('Recommendations:') for rec in result['recommendations']: print(f"- {rec['description']} ({rec['priority']} priority)") return result # Usage examples defi_policy = { 'id': 'defi_access_policy', 'name': 'DeFi Protocol Access', 'description': 'Access policy for DeFi protocols', 'requirements': [ { 'type': 'trustScore', 'operator': 'gte', 'value': 70, 'weight': 0.4, 'required': True }, { 'type': 'attestation', 'operator': 'contains', 'value': 'skill', 'weight': 0.3, 'required': True } ], 'threshold': 75 } evaluate_policy(defi_policy, 'alice.zks', { 'service': 'defi_protocol', 'action': 'lending' }) ``` ## Response Example ```json theme={null} { "success": true, "passed": true, "score": 82.5, "threshold": 75, "subject": "alice.zks", "policy": { "id": "defi_access_policy", "name": "DeFi Protocol Access", "description": "Access policy for DeFi protocols" }, "requirements": [ { "type": "trustScore", "passed": true, "score": 85.0, "weight": 0.4, "required": true, "details": { "currentScore": 85.0, "requiredScore": 70.0, "difference": 15.0 } }, { "type": "attestation", "passed": true, "score": 90.0, "weight": 0.3, "required": true, "details": { "schema": "skill", "count": 3, "averageTrustScore": 90.0 } }, { "type": "attestation", "passed": true, "score": 75.0, "weight": 0.3, "required": false, "details": { "schema": "relationship", "count": 2, "averageTrustScore": 75.0 } } ], "attestations": [ { "id": "att_1234567890abcdef", "schema": "skill", "trustScore": 90.0, "relevance": 0.9 }, { "id": "att_abcdef1234567890", "schema": "relationship", "trustScore": 75.0, "relevance": 0.7 } ], "breakdown": { "trustScore": 85.0, "attestationScore": 82.5, "skillScore": 90.0, "relationshipScore": 75.0, "achievementScore": 0.0 }, "recommendations": [ { "type": "improvement", "description": "Consider adding more relationship attestations to improve your score", "impact": 5.0, "priority": "medium" }, { "type": "maintenance", "description": "Your current score is good, maintain your existing attestations", "impact": 0.0, "priority": "low" } ], "timestamp": "2024-01-20T15:45:00Z" } ``` ## Use Cases ### 1. Access Control Implement trust-based access control: ```javascript theme={null} async function checkAccess(subject, service, action) { const policy = await getAccessPolicy(service, action); const result = await evaluatePolicy(policy, subject, { service, action }); return { allowed: result.passed, score: result.score, threshold: result.threshold, requirements: result.requirements, recommendations: result.recommendations }; } // Usage const access = await checkAccess('alice.zks', 'defi_protocol', 'lending'); if (access.allowed) { console.log('Access granted'); } else { console.log('Access denied. Recommendations:', access.recommendations); } ``` ### 2. Credential Verification Verify user credentials: ```javascript theme={null} async function verifyCredentials(subject, requiredCredentials) { const policy = { id: 'credential_verification', name: 'Credential Verification', description: 'Verify required credentials', requirements: requiredCredentials.map(cred => ({ type: 'attestation', operator: 'contains', value: cred.schema, weight: cred.weight || 1.0, required: cred.required !== false })), threshold: 80 }; return await evaluatePolicy(policy, subject); } // Usage const credentials = [ { schema: 'skill', weight: 0.4, required: true }, { schema: 'identity', weight: 0.3, required: true }, { schema: 'reputation', weight: 0.3, required: false } ]; const verification = await verifyCredentials('alice.zks', credentials); ``` ### 3. Service Eligibility Check eligibility for services: ```javascript theme={null} async function checkEligibility(subject, service) { const policies = await getServicePolicies(service); const results = await Promise.all( policies.map(policy => evaluatePolicy(policy, subject)) ); const overallPassed = results.every(result => result.passed); const averageScore = results.reduce((sum, result) => sum + result.score, 0) / results.length; return { eligible: overallPassed, averageScore, results, recommendations: results.flatMap(r => r.recommendations) }; } ``` ### 4. Policy Testing Test policies before deployment: ```javascript theme={null} async function testPolicy(policy, testSubjects) { const results = await Promise.all( testSubjects.map(subject => evaluatePolicy(policy, subject)) ); const analysis = { totalTests: results.length, passed: results.filter(r => r.passed).length, failed: results.filter(r => !r.passed).length, averageScore: results.reduce((sum, r) => sum + r.score, 0) / results.length, scoreDistribution: analyzeScoreDistribution(results), commonFailures: identifyCommonFailures(results) }; return analysis; } ``` ### 5. Policy Optimization Optimize policies based on results: ```javascript theme={null} function optimizePolicy(policy, evaluationResults) { const failedRequirements = evaluationResults .filter(r => !r.passed) .flatMap(r => r.requirements.filter(req => !req.passed)); const optimization = { adjustThreshold: calculateThresholdAdjustment(failedRequirements), modifyRequirements: suggestRequirementChanges(failedRequirements), addRequirements: suggestNewRequirements(evaluationResults), removeRequirements: suggestRequirementRemoval(failedRequirements) }; return optimization; } ``` ## Best Practices ### 1. Policy Design Design effective policies: ```javascript theme={null} function createEffectivePolicy(requirements, threshold) { return { id: generatePolicyId(), name: 'Effective Policy', description: 'Well-designed policy', requirements: requirements.map(req => ({ ...req, weight: req.weight || 1.0, required: req.required !== false })), threshold: threshold || 70, conditions: createLogicalConditions(requirements) }; } ``` ### 2. Caching Cache policy evaluations: ```javascript theme={null} let policyCache = new Map(); const CACHE_TTL = 5 * 60 * 1000; // 5 minutes async function getCachedPolicyEvaluation(policy, subject) { const cacheKey = `${policy.id}-${subject}`; const cached = policyCache.get(cacheKey); if (cached && Date.now() - cached.timestamp < CACHE_TTL) { return cached.data; } const data = await evaluatePolicy(policy, subject); policyCache.set(cacheKey, { data, timestamp: Date.now() }); return data; } ``` ### 3. Error Handling Handle evaluation errors: ```javascript theme={null} async function safeEvaluatePolicy(policy, subject) { try { return await evaluatePolicy(policy, subject); } catch (error) { if (error.message.includes('Policy not found')) { throw new Error('Invalid policy'); } else if (error.message.includes('Subject not found')) { throw new Error('Invalid subject'); } else { throw new Error('Evaluation failed'); } } } ``` ### 4. Monitoring Monitor policy performance: ```javascript theme={null} function monitorPolicyPerformance(policy, evaluations) { const metrics = { totalEvaluations: evaluations.length, passRate: evaluations.filter(e => e.passed).length / evaluations.length, averageScore: evaluations.reduce((sum, e) => sum + e.score, 0) / evaluations.length, commonFailures: identifyCommonFailures(evaluations), performanceTrends: analyzePerformanceTrends(evaluations) }; return metrics; } ``` ## Related Endpoints * [Get Attestations](/api-reference/trust-layer/get-attestations) - Retrieve attestations * [Create Attestation](/api-reference/trust-layer/create-attestation) - Create new attestations * [Revoke Attestation](/api-reference/trust-layer/revoke-attestation) - Revoke attestations * [Get Modules](/api-reference/trust-layer/get-modules) - Get available trust modules ## Troubleshooting ### "Policy not found" **Cause**: Invalid policy ID or policy doesn't exist. **Solution**: * Verify the policy ID is correct * Check if the policy exists * Ensure you have access to the policy ### "Subject not found" **Cause**: Invalid subject identity or subject doesn't exist. **Solution**: * Verify the subject identity is correct * Check if the subject exists * Ensure the subject has some activity ### "Invalid policy format" **Cause**: Policy structure is invalid. **Solution**: * Check the policy structure * Ensure all required fields are present * Validate the policy format ### "Evaluation failed" **Cause**: Internal error during evaluation. **Solution**: * Check the policy requirements * Verify the subject data * Contact support if the issue persists ## Rate Limits Policy evaluation requests are subject to rate limits: * **Free tier**: 60 requests per minute * **Starter tier**: 300 requests per minute * **Professional tier**: 1,000 requests per minute * **Enterprise tier**: Custom limits Implement caching to reduce API calls.