Skip to main content
DELETE
https://api-mainnet.onzks.com
/
v1
/
trust
/
attestations
/
:attestationId
Revoke Attestation
curl --request DELETE \
  --url https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>",
  "details": "<string>",
  "signature": "<string>",
  "notifySubject": true,
  "publicReason": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "attestationId": "<string>",
  "attestation": {
    "id": "<string>",
    "subject": "<string>",
    "issuer": "<string>",
    "schema": "<string>",
    "data": {},
    "createdAt": "<string>",
    "revokedAt": "<string>",
    "revocationReason": "<string>",
    "revocationDetails": "<string>",
    "publicReason": "<string>",
    "status": "<string>"
  },
  "impact": {
    "subjectNotified": true,
    "trustScoreImpact": 123,
    "relatedAttestations": 123,
    "publicVisibility": true
  },
  "timestamp": "<string>"
}

​
Overview

Revoke an existing attestation that you have issued. This endpoint allows attestation issuers to revoke their attestations when circumstances change, providing a mechanism for maintaining the integrity of the trust system.
Use this endpoint to revoke attestations when relationships change, skills become outdated, or when you need to correct erroneous attestations. Only the original issuer can revoke an attestation.

​
Parameters

​
attestationId
string
required
Unique identifier of the attestation to revoke

​
Request Body

​
reason
string
required
Reason for revoking the attestation
  • relationship_ended - Relationship has ended
  • skill_outdated - Skill is no longer current
  • achievement_invalid - Achievement was incorrectly awarded
  • reputation_changed - Reputation has changed
  • identity_verification_failed - Identity verification failed
  • other - Other reason (specify in details)
​
details
string
Additional details about the revocation reason
​
signature
string
required
Cryptographic signature proving ownership of the attestation
​
notifySubject
boolean
Whether to notify the subject about the revocation (default: true)
​
publicReason
string
Public reason for the revocation (visible to others)

​
Response

​
success
boolean
Indicates if the attestation was revoked successfully
​
message
string
Success message
​
attestationId
string
Identifier of the revoked attestation
​
attestation
object
Revoked attestation details
​
impact
object
Impact of the revocation
​
timestamp
string
ISO 8601 timestamp of the response

​
Examples

curl -X DELETE "https://api.onzks.com/v1/trust/attestations/att_1234567890abcdef" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "relationship_ended",
    "details": "Business partnership has been terminated",
    "signature": "0xabcdef1234567890...",
    "notifySubject": true,
    "publicReason": "Partnership ended"
  }'

​
Response Example

{
  "success": true,
  "message": "Attestation revoked successfully",
  "attestationId": "att_1234567890abcdef",
  "attestation": {
    "id": "att_1234567890abcdef",
    "subject": "alice.zks",
    "issuer": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "schema": "relationship",
    "data": {
      "title": "Business Partner",
      "description": "Long-term business partnership",
      "category": "business",
      "value": "trusted",
      "metadata": {
        "relationshipType": "business_partner",
        "duration": "3 years",
        "projects": ["Joint Venture", "Consulting"]
      }
    },
    "createdAt": "2024-01-10T14:20:00Z",
    "revokedAt": "2024-01-20T15:45:00Z",
    "revocationReason": "relationship_ended",
    "revocationDetails": "Business partnership has been terminated",
    "publicReason": "Partnership ended",
    "status": "revoked"
  },
  "impact": {
    "subjectNotified": true,
    "trustScoreImpact": -5.2,
    "relatedAttestations": 2,
    "publicVisibility": true
  },
  "timestamp": "2024-01-20T15:45:00Z"
}

​
Use Cases

​
1. Relationship Management

Revoke attestations when relationships end: 
async function revokeRelationshipAttestation(attestationId, reason, details) {
  const revocationData = {
    reason: 'relationship_ended',
    details: details,
    signature: await signRevocation(attestationId, reason),
    notifySubject: true,
    publicReason: 'Relationship ended'
  };

  return await revokeAttestation(attestationId, revocationData);
}

// Usage
await revokeRelationshipAttestation(
  'att_1234567890abcdef',
  'Business partnership has been terminated'
);

​
2. Skill Updates

Revoke outdated skill attestations: 
async function revokeOutdatedSkill(attestationId, newTechnology) {
  const revocationData = {
    reason: 'skill_outdated',
    details: `Technology stack has changed to ${newTechnology}`,
    signature: await signRevocation(attestationId, 'skill_outdated'),
    notifySubject: true,
    publicReason: 'Technology outdated'
  };

  return await revokeAttestation(attestationId, revocationData);
}

// Usage
await revokeOutdatedSkill('att_abcdef1234567890', 'React 18');

​
3. Achievement Corrections

Revoke incorrectly awarded achievements: 
async function revokeIncorrectAchievement(attestationId, correction) {
  const revocationData = {
    reason: 'achievement_invalid',
    details: `Achievement was incorrectly awarded: ${correction}`,
    signature: await signRevocation(attestationId, 'achievement_invalid'),
    notifySubject: true,
    publicReason: 'Incorrectly awarded'
  };

  return await revokeAttestation(attestationId, revocationData);
}

// Usage
await revokeIncorrectAchievement(
  'att_9876543210fedcba',
  'System error caused incorrect achievement award'
);

​
4. Batch Revocation

Revoke multiple attestations at once: 
async function revokeMultipleAttestations(attestationIds, reason, details) {
  const results = [];
  
  for (const attestationId of attestationIds) {
    try {
      const result = await revokeAttestation(attestationId, {
        reason,
        details,
        signature: await signRevocation(attestationId, reason),
        notifySubject: true
      });
      results.push({ attestationId, success: true, result });
    } catch (error) {
      results.push({ attestationId, success: false, error: error.message });
    }
  }
  
  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);
  
  console.log(`Successfully revoked ${successful.length} attestations`);
  if (failed.length > 0) {
    console.log(`Failed to revoke ${failed.length} attestations`);
  }
  
  return results;
}

​
5. Revocation Analytics

Analyze revocation patterns: 
function analyzeRevocations(revokedAttestations) {
  const analysis = {
    byReason: groupBy(revokedAttestations, 'revocationReason'),
    bySchema: groupBy(revokedAttestations, 'schema'),
    byTimeframe: groupByTimeframe(revokedAttestations),
    averageImpact: calculateAverageImpact(revokedAttestations),
    trends: identifyRevocationTrends(revokedAttestations)
  };
  
  return analysis;
}

function groupBy(array, key) {
  return array.reduce((groups, item) => {
    const value = item[key];
    if (!groups[value]) {
      groups[value] = [];
    }
    groups[value].push(item);
    return groups;
  }, {});
}

​
Best Practices

​
1. Signature Verification

Always verify signatures before revoking: 
async function verifyRevocationSignature(attestationId, reason, signature) {
  const message = JSON.stringify({
    attestationId,
    reason,
    timestamp: Date.now()
  });
  
  const recoveredAddress = await recoverAddress(message, signature);
  return recoveredAddress === attestation.issuer;
}

​
2. Impact Assessment

Assess the impact before revoking: 
async function assessRevocationImpact(attestationId) {
  const attestation = await getAttestation(attestationId);
  
  const impact = {
    trustScoreImpact: calculateTrustScoreImpact(attestation),
    relatedAttestations: await findRelatedAttestations(attestation),
    subjectImpact: await assessSubjectImpact(attestation.subject),
    publicImpact: assessPublicImpact(attestation)
  };
  
  return impact;
}

​
3. Notification Management

Handle notifications appropriately: 
function shouldNotifySubject(attestation, reason) {
  const notificationReasons = [
    'relationship_ended',
    'skill_outdated',
    'achievement_invalid'
  ];
  
  return notificationReasons.includes(reason) && attestation.public;
}

​
4. Audit Trail

Maintain audit trail for revocations: 
function createRevocationAudit(attestation, revocationData) {
  return {
    attestationId: attestation.id,
    subject: attestation.subject,
    issuer: attestation.issuer,
    originalData: attestation.data,
    revocationReason: revocationData.reason,
    revocationDetails: revocationData.details,
    revokedAt: new Date().toISOString(),
    revokedBy: revocationData.issuer,
    signature: revocationData.signature
  };
}

​
Troubleshooting

​
”Attestation not found”

Cause: Invalid attestation ID or attestation doesn’t exist. Solution:
  • Verify the attestation ID is correct
  • Check if the attestation exists
  • Ensure you have access to the attestation

​
”Not authorized to revoke”

Cause: You are not the issuer of the attestation. Solution:
  • Only the original issuer can revoke an attestation
  • Verify you are using the correct account
  • Check the attestation issuer

​
”Attestation already revoked”

Cause: The attestation has already been revoked. Solution:
  • Check the attestation status
  • You cannot revoke an already revoked attestation
  • Consider the impact of the previous revocation

​
”Invalid signature”

Cause: The signature doesn’t match the revocation data. Solution:
  • Verify the signature is correctly generated
  • Ensure the message being signed matches the revocation data
  • Check that the correct private key is being used

​
Rate Limits

Attestation revocation requests are subject to rate limits:
  • Free tier: 10 revocations per minute
  • Starter tier: 50 revocations per minute
  • Professional tier: 200 revocations per minute
  • Enterprise tier: Custom limits
Implement queuing for batch revocations to avoid rate limits.